# Zed Markitdown Mcp

> Give your AI agent a convert_to_markdown tool to read PDF/DOCX/XLSX/PPTX/images by path — and ~10-18x cheaper than native PDF reading. markitdown as a Zed MCP context server, with a self-healing health check.

- **Type:** MCP server
- **Install:** `agentstack add mcp-joaquinruz-zed-markitdown-mcp`
- **Verified:** Pending review
- **Seller:** [JoaquinRuz](https://agentstack.voostack.com/s/joaquinruz)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [JoaquinRuz](https://github.com/JoaquinRuz)
- **Source:** https://github.com/JoaquinRuz/zed-markitdown-mcp

## Install

```sh
agentstack add mcp-joaquinruz-zed-markitdown-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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`](https://github.com/microsoft/markitdown) as a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) context server for [Zed](https://zed.dev), 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](https://zed.dev) (or any MCP client — see the note under Install)
- [`uv`](https://docs.astral.sh/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)

```bash
./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:

```jsonc
{
  "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:

```bash
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](https://github.com/microsoft/markitdown) — the conversion engine and the `markitdown-mcp` server.
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Zed](https://zed.dev)

## 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](https://github.com/JoaquinRuz)
- **Source:** [JoaquinRuz/zed-markitdown-mcp](https://github.com/JoaquinRuz/zed-markitdown-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-joaquinruz-zed-markitdown-mcp
- Seller: https://agentstack.voostack.com/s/joaquinruz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.