Zed Markitdown Mcp

zed-markitdown-mcp

Give your AI agent a convert_to_markdown tool so it can read PDF, DOCX, XLSX, PPTX, and images — and read them cheaply. Wires up Microsoft's markitdown as a Model Context Protocol (MCP) context server for Zed, with a self-healing health check so you can prove it works.

What it does

Zed's agent works with text. On its own it can't read binary documents — a PDF or Word file is opaque to it. This registers markitdown as an MCP context server, which hands the agent a convert_to_markdown tool. Point it at a file path or URL and it gets back clean Markdown:

• PDF, DOCX, XLSX, PPTX
• images (PNG / JPG)
• HTML, CSV, JSON, and more

The agent reads documents by path — you give it the path, it converts and reads. See [Usage](#usage).

Why it's worth it: token savings

The point isn't only "the agent can read a PDF" — it's how cheaply. When an agent reads a PDF the native way, **each page is sent to the model as extracted text plus a rendered image of the page (~1,500–3,000 tokens per page). markitdown extracts only the text** and skips the image layer entirely.

For a text-heavy PDF that's roughly 10–18× fewer tokens:

> A 15-page text PDF ≈ 22,000–45,000 tokens read natively vs. ≈ 2,000–2,500 tokens via markitdown.

The trade-off — text only. Skipping the image layer means you lose the visuals. For scanned PDFs, charts, diagrams, or layout-heavy pages, let the agent read natively instead — that's exactly when the page images carry the information.

| Document | Use markitdown | Read it natively | |---|:---:|:---:| | Text PDF, reports, contracts, email threads | ✅ big token savings | | | DOCX / XLSX / PPTX | ✅ clean Markdown + tables | | | Scanned PDF, charts, diagrams, screenshots | | ✅ needs the image layer |

agent ──stdio MCP──▶ uvx markitdown-mcp ──▶ markitdown ──▶ Markdown text

Requirements

• Zed (or any MCP client — see the note under Install)
• uv, which provides uvx:

``bash curl -LsSf https://astral.sh/uv/install.sh | sh # macOS / Linux ` uv` manages its own Python, so you do not need a separate Python 3.10+ install.

Install

1. Warm the cache and verify (do this first)

./install.sh

This locates uvx, downloads markitdown-mcp once, runs the health check against generated sample files, and prints the exact settings snippet — with the correct absolute uvx path for your machine.

2. Add the context server to Zed

Open your Zed settings.json (cmd/ctrl + ,) and add a context_servers block:

{
  "context_servers": {
    "markitdown": {
      "command": "uvx",
      "args": ["markitdown-mcp"],
      "env": {}
    }
  }
}

> macOS tip: Zed launched from the Dock doesn't always inherit your shell PATH, so a bare uvx may be "not found". Use the absolute path instead (e.g. /opt/homebrew/bin/uvx). install.sh prints the right one for you.

Settings location:

| OS | Path | |----|------| | macOS / Linux | ~/.config/zed/settings.json | | Windows | %APPDATA%\Zed\settings.json |

Zed hot-reloads settings; the markitdown server should appear in the Agent panel. Restart Zed or open a new agent thread if it doesn't show up.

> Using Claude Code (or another MCP client)? context_servers only feeds Zed's native agent — external agents (e.g. Claude Code via ACP) don't see it. Register the same server with that client instead. For Claude Code: > ``bash > claude mcp add markitdown -s user -- uvx markitdown-mcp > ``

Usage

1. Get the file's path — in Zed, right-click it in the project tree → Copy Path (or use any absolute path / URL).
2. In an agent thread, paste the path and ask: "read this document with markitdown".
3. The agent calls convert_to_markdown and reads it.

To force the cheap text path on a PDF, say "use markitdown". For a scanned or visual PDF, ask the agent to read it natively instead.

> This is path-based, not drag-and-drop. Dropping a binary into Zed's chat won't attach it — Zed's chat only accepts text, so it rejects PDFs/DOCX with "Binary files are not supported". That's a Zed limitation this tool doesn't change; the workflow is to give the agent the path and let it convert.

Verify

Re-run the health check any time:

python3 verify_markitdown_mcp.py                     # self-test (auto-generated samples)
python3 verify_markitdown_mcp.py mydoc.pdf file.docx # test your own files

RESULT: PASS means the MCP server is healthy and actually converts files. What the checker does:

• drives the full MCP stdio handshake (initialize → tools/list → tools/call),
• actually converts files and asserts non-empty Markdown comes back,
• with no arguments, generates a throwaway sample PDF and DOCX (no third-party deps, no personal data),
• retries the whole sweep with backoff if it fails because of a transient network hiccup.

Troubleshooting

| Symptom | Cause / fix | |---------|-------------| | Server shows as errored | Almost always PATH. Use the absolute uvx path in your config. | | First launch is slow | First run downloads packages (once). Later launches use the uv cache. | | uvx: command not found | Install uv (see Requirements) and reopen the client. | | Health check fails with a network error | The script auto-retries; if it persists, check connectivity to pypi.org. | | Agent reads a PDF "the expensive way" | It won't auto-prefer markitdown — tell it "use markitdown" to force the text path. |

Credits

• microsoft/markitdown — the conversion engine and the markitdown-mcp server.
• Model Context Protocol
• Zed

License

MIT — see [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: JoaquinRuz
• Source: JoaquinRuz/zed-markitdown-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.