MCP Server

Overview

The Web2MD MCP server exposes Web2MD as a set of tools that AI assistants can call directly, using the Model Context Protocol (MCP) — an open standard for connecting AI models to external tools and data sources. Once configured, you can ask Claude, Cursor, or Windsurf to convert pages, search and sync your Library, batch-convert with the Chrome extension, or pull in a saved Skill — without leaving the conversation.

The MCP server requires a Web2MD API key (PRO plan). Generate one from the dashboard, or run npx web2md-cli login to authenticate once and share the key with the CLI automatically (see Authentication below).

Connect claude.ai — no install

Web2MD also runs as a remote MCP server, so you can use it on claude.ai without installing anything:

In claude.ai, open Settings → Connectors → Add custom connector
Enter the URL: https://web2md.org/api/mcp
Complete the sign-in when prompted (OAuth — Google or email magic link)

The remote server exposes convert_url, search_library and get_conversion. Custom connectors require a paid claude.ai plan.

One-command setup for local Agents

One command detects and configures every Agent on your machine — Claude Code, Codex, Cursor and Claude Desktop:

npm i -g web2md-mcp-server@latest && web2md-mcp-setup

It signs you in, registers the local extension bridge, then writes the MCP config for each client it finds. Skip the rest of this page unless you want manual control.

Available tools

The MCP server provides 11 tools, grouped by what they do:

Tool	Description
`convert_url`	Convert any URL to clean Markdown via the server-side converter
`convert_file`	Convert a local document (Word, PowerPoint, Excel, PDF, EPUB, CSV, …) to Markdown — fast and fully local, the file never leaves your machine
`bridge_convert_url`	Convert a URL through your Chrome extension over HTTP — for Reddit, JS-rendered, or login-protected pages
`agent_convert`	Convert a URL through the Chrome extension via native messaging (same use cases as `bridge_convert_url`, different transport)
`agent_batch_convert`	Batch-convert up to 50 URLs through the Chrome extension via native messaging
`search_library`	Search your saved Library by keyword and/or tag
`get_library_items`	Fetch full Markdown for Library items by id
`sync_library`	Sync your Library to a local directory as Markdown files
`list_skills`	List the Skills saved in your Web2MD cloud account
`get_skill`	Fetch the full body of one Skill by id or name
`semantic_search`	Deprecated — use `search_library` + `get_library_items` instead
`get_conversion`	Deprecated — use `search_library` + `get_library_items` instead

convert_url

Fetches a URL server-side and returns the page content as Markdown, with title, word count, and reading time. Supports the same conversion options as the REST API (includeImages, includeLinks). Example prompt: “Convert this URL to markdown: https://docs.example.com/getting-started”

bridge_convert_url

Converts a URL by fetching its HTML through your running Chrome extension (over a local HTTP bridge), then converting that HTML to Markdown server-side. Use this for pages the server can’t reach directly — Reddit, sites gated behind login, or heavily JS-rendered pages. Requires Chrome open with the Web2MD extension installed; the extension ID is auto-discovered from your API key. Example prompt: “Use the bridge to convert this Reddit thread: https://reddit.com/r/…“

agent_convert

Converts a URL the same way bridge_convert_url does — through your Chrome extension — but over the Agent Bridge native-messaging channel instead of HTTP. Accepts an optional skill parameter: pass a Skill id or name and its body is appended to the returned Markdown so the agent can act on it immediately. Requires Chrome running with the extension and native host installed. Example prompt: “Convert this page with the summarize skill applied: https://…“

agent_batch_convert

Same transport as agent_convert, but takes an array of up to 50 URLs and converts them sequentially in one call. Best for pulling many Reddit threads or JS-rendered pages in one go. Example prompt: “Batch-convert these 12 URLs to Markdown: […]“

search_library

Searches your Web2MD Library — every page you’ve saved — by keyword (matches title and full page content) and/or tag, newest first. Returns compact metadata (id, title, url, date, tags), not the full Markdown. Free-plan accounts only see the most recent items in results; the tool tells you when results were truncated. Example prompt: “Search my library for anything about authentication”

get_library_items

Fetches full Markdown content for Library items by id (up to 20 per call — use search_library first to find the ids). Responses can be large; for long pages, batch 5 or fewer ids per call. Example prompt: “Get the full content of library items abc123 and def456”

sync_library

Syncs your entire Library to a local directory as Markdown files, organized by tag with frontmatter. Incremental by default (tracks a cursor in <dir>/.web2md-sync.json); pass full: true to re-scan everything. This is the same sync that web2md sync runs from the CLI — use whichever surface fits your workflow. Example prompt: “Sync my library to ~/notes/web2md, tag ‘research’ only”

list_skills

Lists the Skills saved in your Web2MD cloud account as a compact array (id, name, description). Use get_skill to fetch one in full. Example prompt: “What skills do I have saved?“

get_skill

Fetches the full SKILL.md-style body of one Skill by id or name — its instructions, description, and content in full. Use list_skills first if you don’t know the id. Example prompt: “Get my ‘summarize’ skill”

semantic_search / get_conversion (deprecated)

These two tools predate the Library. They still work but only see conversions saved through the old history API, not the full Library — new integrations should use search_library and get_library_items instead.

Authentication

The server resolves the API key in this order:

WEB2MD_API_KEY environment variable, if set.
Otherwise, ~/.web2md/config.json — the same file written by npx web2md-cli login (the CLI’s device-login flow). Run login once and both the CLI and MCP server pick up the key automatically, no env block needed.

If neither is found, the server starts but every tool call returns an authentication error with a hint to set the key or run login.

Setup

Claude Desktop
Cursor
Windsurf

Open your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the web2md entry under mcpServers:

{
  "mcpServers": {
    "web2md": {
      "command": "npx",
      "args": ["-y", "web2md-mcp-server"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

If you’ve already run npx web2md-cli login, you can drop the env block entirely — the server reads the key from ~/.web2md/config.json.Restart Claude Desktop. You should see the Web2MD tools appear in the tool picker.

Open your Cursor MCP configuration file at ~/.cursor/mcp.json and add:

{
  "mcpServers": {
    "web2md": {
      "command": "npx",
      "args": ["-y", "web2md-mcp-server"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

Restart Cursor to load the new server.

Open your Windsurf MCP configuration file at ~/.windsurf/mcp.json and add:

{
  "mcpServers": {
    "web2md": {
      "command": "npx",
      "args": ["-y", "web2md-mcp-server"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

Restart Windsurf to load the new server.

Usage examples

Once the MCP server is running, you can use natural language in your AI assistant:

Convert a page to Markdown

You: Convert this URL to markdown: https://react.dev/learn/thinking-in-reactAssistant: (calls convert_url) Here is the converted Markdown for “Thinking in React”…

Search and pull from your Library

You: Search my library for anything about authentication, then get the full content of the most recent oneAssistant: (calls search_library, then get_library_items) I found 3 items related to authentication. Here’s the full content of the most recent one, “OAuth 2.0 Guide”…

Sync your Library locally

You: Sync my library to ~/notes/web2mdAssistant: (calls sync_library) Synced 42 new items, 118 already up to date, 0 failed.

Batch-convert with the extension

You: Batch-convert these 8 Reddit threads: […]Assistant: (calls agent_batch_convert) Converted 8/8 URLs successfully.

Apply a saved Skill

You: What skills do I have, and can you apply “summarize” to this page: https://…Assistant: (calls list_skills, then agent_convert with skill: "summarize") Here’s the page converted to Markdown, with the summarize skill applied below it…

Combine tools in a single conversation. For example: “Search my library for React docs, then get the full content of the most recent one.”

Troubleshooting

Tools don't appear after setup

Make sure you have restarted the application after editing the configuration file. Verify that npx -y web2md-mcp-server runs successfully in your terminal.

Authentication errors

Double-check that WEB2MD_API_KEY is a valid w2m_ key, or that ~/.web2md/config.json has one (re-run npx web2md-cli login if unsure). You can verify your key on the API keys page.

agent_convert / agent_batch_convert / bridge_convert_url fail

These tools require Chrome open with the Web2MD extension installed, and — for the agent_* tools — the native host installed too. See Agent Bridge for setup.

npx fails to resolve the package

Try installing the package globally first: npm install -g web2md-mcp-server, then change command to web2md-mcp-server and remove the args field.

Getting Started

Core Features

Advanced

Plans

Overview

Connect claude.ai — no install

One-command setup for local Agents

Available tools

convert_url

bridge_convert_url

agent_convert

agent_batch_convert

search_library

get_library_items

sync_library

list_skills

get_skill

semantic_search / get_conversion (deprecated)

Authentication

Setup

Usage examples

Troubleshooting

​Overview

​Connect claude.ai — no install

​One-command setup for local Agents

​Available tools

​convert_url

​bridge_convert_url

​agent_convert

​agent_batch_convert

​search_library

​get_library_items

​sync_library

​list_skills

​get_skill

​semantic_search / get_conversion (deprecated)

​Authentication

​Setup

​Usage examples

​Troubleshooting

Overview

Connect claude.ai — no install

One-command setup for local Agents

Available tools

convert_url

bridge_convert_url

agent_convert

agent_batch_convert

search_library

get_library_items

sync_library

list_skills

get_skill

semantic_search / get_conversion (deprecated)

Authentication

Setup

Usage examples

Troubleshooting