Web2MD Agent Bridge
Convert any web page to clean Markdown and search your saved research library from Claude, ChatGPT, Cursor, and other MCP-compatible agents.
Hosted MCP Server
npx add-mcp 'https://web2md.org/api/mcp'Installs into Claude Code, Codex, Cursor and more
Documentation
MCP Server
Use Web2MD from Claude Desktop, Cursor, and Windsurf
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.
[!NOTE]
The MCP server requires a Web2MD API key (PRO plan). Generate one from the dashboard, or run
npx web2md-cli loginto 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_KEYenvironment variable, if set.- Otherwise,
~/.web2md/config.json— the same file written bynpx web2md-cli login(the CLI's device-login flow). Runloginonce and both the CLI and MCP server pick up the key automatically, noenvblock 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
[tab] Claude Desktop
Open your Claude Desktop configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json- Windows:
%APPDATA%\Claude\claude_desktop_config.jsonAdd the
web2mdentry undermcpServers:{ "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 theenvblock entirely — the server reads the key from~/.web2md/config.json.Restart Claude Desktop. You should see the Web2MD tools appear in the tool picker.
[tab] Cursor
Open your Cursor MCP configuration file at
~/.cursor/mcp.jsonand 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.
[tab] Windsurf
Open your Windsurf MCP configuration file at
~/.windsurf/mcp.jsonand 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:
[accordion] Convert a page to Markdown
You: Convert this URL to markdown: https://react.dev/learn/thinking-in-react
Assistant: (calls
convert_url) Here is the converted Markdown for "Thinking in React"...
[accordion] Search and pull from your Library
You: Search my library for anything about authentication, then get the full content of the most recent one
Assistant: (calls
search_library, thenget_library_items) I found 3 items related to authentication. Here's the full content of the most recent one, "OAuth 2.0 Guide"...
[accordion] Sync your Library locally
You: Sync my library to ~/notes/web2md
Assistant: (calls
sync_library) Synced 42 new items, 118 already up to date, 0 failed.
[accordion] Batch-convert with the extension
You: Batch-convert these 8 Reddit threads: [...]
Assistant: (calls
agent_batch_convert) Converted 8/8 URLs successfully.
[accordion] Apply a saved Skill
You: What skills do I have, and can you apply "summarize" to this page: https://...
Assistant: (calls
list_skills, thenagent_convertwithskill: "summarize") Here's the page converted to Markdown, with the summarize skill applied below it...
[!TIP]
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
[accordion] Tools don't appear after setup
Make sure you have restarted the application after editing the configuration file. Verify that
npx -y web2md-mcp-serverruns successfully in your terminal.
[accordion] Authentication errors
Double-check that
WEB2MD_API_KEYis a validw2m_key, or that~/.web2md/config.jsonhas one (re-runnpx web2md-cli loginif unsure). You can verify your key on the API keys page.
[accordion] 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.
[accordion] npx fails to resolve the package
Try installing the package globally first:
npm install -g web2md-mcp-server, then changecommandtoweb2md-mcp-serverand remove theargsfield.
This documentation is built and hosted on Mintlify, a developer documentation platform.