Skip to main content
Glama
README.md
# web2md-mcp

[![npm version](https://img.shields.io/npm/v/web2md-mcp-server.svg)](https://www.npmjs.com/package/web2md-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-compatible-blue)](https://modelcontextprotocol.io)

**Convert any webpage to clean Markdown from Claude Desktop, Cursor, or any MCP-compatible AI agent.**

`web2md-mcp` is the official [Model Context Protocol](https://modelcontextprotocol.io) server for [Web2MD](https://web2md.org). Give your AI agent a `convert_url` tool and it can turn any webpage — articles, docs, Reddit threads, GitHub READMEs — into clean, token-efficient Markdown without copy-pasting.

> Unlike server-side readers, the optional **Agent Bridge** mode routes conversion through your real browser session — so it works on Reddit, X, paywalled Substack, and other pages that block datacenter scrapers.

---

## Why use this?

The honest version: most webpage-to-Markdown tools convert HTML well. The thing
they differ on is **whether they can reach the page at all**.

| | web2md-mcp | Jina Reader / Firecrawl | MarkDownload / SingleFile | Turndown |
|---|---|---|---|---|
| Clean Markdown built for LLM context | ✅ | ✅ | ✅ | ✅ (library only) |
| Callable by an AI agent (MCP) | ✅ | via HTTP API | ❌ manual click | ❌ |
| Works on Reddit / X / paywalled pages | ✅ (Agent Bridge) | ❌ blocked by anti-bot | ✅ (you click it) | n/a |
| Uses *your* authenticated session | ✅ (Agent Bridge) | ❌ datacenter fetch | ✅ | n/a |
| Batch convert many URLs unattended | ✅ up to 50 | ✅ | ❌ one at a time | ❌ |
| Token counting + metadata | ✅ | ⚠️ varies | ❌ | ❌ |

**Where each one is the right answer:**

- **Jina Reader / Firecrawl** — public pages at scale, no browser needed. If your
  URLs are public docs or blogs, these are simpler than running an extension.
- **MarkDownload / SingleFile / Obsidian Web Clipper** — you're reading a page and
  want to save it yourself. Great at that; they need a human to click.
- **Turndown** — an HTML→Markdown library, not a fetcher. Use it inside your own code.
- **web2md-mcp** — an *agent* needs the page, and the page is behind a login, a
  bot wall, or heavy JS. That's the gap this fills: conversion happens in your
  real browser session, so the page sees you, not a datacenter IP.

If you've hit "I can't access that URL" in Claude or Cursor when pasting a
Reddit/X/Substack link, this is the fix.

---

## Install

```bash
npx -p web2md-mcp-server web2md-mcp-setup
```

That detects your MCP clients, writes their config, and — only if you ask for a
tool that needs an account — opens the browser for OAuth. No password is typed
anywhere.

### Manual config

`~/.claude/claude_desktop_config.json` or `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "web2md": { "command": "npx", "args": ["-y", "-p", "web2md-mcp-server", "web2md-mcp"] }
  }
}
```

Restart the client afterwards.

**No account needed to start.** `convert_url` and `convert_file` work as soon as
the server is installed. A free API key is only required for the library and
skill tools — add `"env": { "WEB2MD_API_KEY": "w2m_..." }` to the block above,
or let the setup command handle it.

---

## Tools

Twelve tools, grouped by what they need.

### Works without an account

**`convert_url`** — convert a webpage to Markdown.
```jsonc
{ "url": "https://example.com/article" }
```

**`convert_file`** — convert a local document (Word, PowerPoint, Excel, PDF).
Needs the optional `@firecrawl/anydoc` dependency; the tool says so if it is missing.

### Reads your signed-in browser

These go through the Web2MD Chrome extension, so they see what *you* see — pages
behind a login, or ones that only render after JavaScript runs. A server-side
fetch gets a login wall for those.

**`bridge_convert_url`** — one URL through the extension. Auto-discovers your
extension via your API key.

**`agent_convert`** / **`agent_batch_convert`** — same idea over native
messaging ([Agent Bridge](https://web2md.org/docs/advanced/agent-bridge) setup).
Batch takes up to 50 URLs per call and reports token counts for each.

### Your saved library

**`search_library`**, **`get_library_items`** (max 20 per call),
**`sync_library`** (mirror the library to a local folder as Markdown),
**`list_skills`**, **`get_skill`**.

`semantic_search` and `get_conversion` still work but are deprecated —
prefer `search_library` / `get_library_items`.

Library and skill tools need a free API key. Run the setup command above and it
walks you through OAuth, or set `WEB2MD_API_KEY` yourself.

---

## Example prompts

Once configured, just ask your agent:

- *"Convert this Reddit thread to markdown and summarize the top arguments."*
- *"Fetch these 10 blog URLs as markdown and build a comparison table."*
- *"Read this GitHub README as clean markdown and explain the setup steps."*

---

## Agent Bridge (browser-based conversion)

Server-side fetching fails on Reddit, X, paywalled Substack/Medium, and JS-heavy SPAs — datacenter IPs get blocked and client-side-rendered content never loads. Agent Bridge solves this by routing the conversion through the Web2MD Chrome extension running in **your** logged-in browser. Setup guide: [web2md.org/docs/advanced/agent-bridge](https://web2md.org/docs/advanced/agent-bridge).

---

## Links

- 🌐 Website: [web2md.org](https://web2md.org)
- 🧩 Chrome Web Store: [Web2MD — Web to Markdown](https://chromewebstore.google.com/detail/web2md-web-to-markdown/ijmgpkkfgpijifldbjafjiapehppcbcn)
- 📖 Docs: [web2md.org/docs](https://web2md.org/docs)
- 🔌 MCP spec: [modelcontextprotocol.io](https://modelcontextprotocol.io)
- ✉️ Support: support@web2md.org

## License

MIT © [Web2MD](https://web2md.org)

TDQS

A3.8/5.0

Scored across 12 tools

Disambiguation3/5

The four conversion tools (convert_url, agent_convert, bridge_convert_url, agent_batch_convert) all target the same action and rely on descriptions rather than distinct purposes to separate them; agent_convert vs bridge_convert_url is purely a mechanism fallback, which is easy to misselect. Deprecated get_conversion and semantic_search still sit alongside their replacements (get_library_items, search_library), creating redundant overlapping pairs. The descriptions are unusually explicit about when to use which, which rescues the set from a lower score.

Naming Consistency4/5

Nearly all tools follow snake_case verb_noun or prefix_noun patterns (get_library_items, list_skills, search_library, sync_library, convert_file). Deviations are minor: the agent_/bridge_ mechanism prefixes and the adjective-first semantic_search break the verb pattern slightly. Still highly readable and predictable overall.

Tool Count4/5

Twelve tools is well within a healthy range for a conversion-plus-library server, and each of the non-deprecated tools maps to a real operation. Two of the twelve are explicitly deprecated and only earn their place as legacy aliases, which is mild dead weight.

Completeness3/5

Conversion coverage is strong (public URL, authenticated browser, batch, local files) and read paths for library and skills exist. However, there is no way to delete or manage library items, and skills are read-only (no create/update/delete), leaving the lifecycle half-covered. The presence of two deprecated tools also suggests the surface has drifted rather than been consolidated.

Maintenance

ActivityMaintained
ResponsivenessOutdated data