Document Converter

📄 Document Converter MCP

Convert documents to Markdown inside Cursor, VS Code, and any MCP client.

Local processing · No cloud upload · Powered by MarkItDown

Give your AI assistant the ability to read PDFs, Office files, spreadsheets, emails, audio, and more as clean Markdown — so it can summarize, search, and reason over content instead of struggling with binary attachments.

---

Table of contents

• Overview 📋
• Use cases 💡
• Features ✨
• Supported formats 📎
• Quick install 🚀
• Before you start
• Cursor 🖱️
• VS Code 💻
• Claude Desktop 🤖
• Verify it works ✅
• Tools 🛠️
• Usage examples 💬
• Local development 🧪
• Configuration reference ⚙️
• MCP Registry 📦
• Troubleshooting 🔧
• License 📜

---

Overview 📋

Document Converter MCP is a lightweight stdio server that wraps Microsoft's MarkItDown library for the Model Context Protocol.

flowchart LR

A[Your file on disk] --> B[Document Converter MCP] B --> C[MarkItDown] C --> D[Markdown in chat or .md file]

Once connected, your agent converts files locally and returns structured text — nothing is sent to a conversion API.

---

Use cases 💡

---

Features ✨

• 🏠 Local-first — files stay on your machine; no third-party conversion service
• 📎 Broad format coverage — PDF, Office, CSV/JSON/text, Outlook .msg, audio, YouTube, and more (via MarkItDown)
• 🔀 Two workflows — save Markdown next to the source, or preview in chat only
• 📋 Copy-paste setup — step-by-step install for Cursor, VS Code, and Claude Desktop
• 📦 Registry published — listed on the official MCP Registry
• ⚖️ MIT licensed — free for personal and commercial use

---

Supported formats 📎

Formats below are verified against MarkItDown 0.1.6 with our installed extras:

markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription]

We avoid markitdown[all] because it pulls Azure pre-release packages that uv cannot resolve with uvx.

Fully supported (with this project's dependencies)

Limited support

Not supported

Conversion quality depends on the source file. See the MarkItDown documentation for upstream details.

---

Quick install 🚀

Follow the steps for your editor. Every config below uses the same command — only the JSON file and wrapper key differ.

Before you start (all editors)

1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/) (includes uvx).

Windows (PowerShell):

   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS / Linux:

   curl -LsSf https://astral.sh/uv/install.sh | sh

1. Verify `uvx` works (open a new terminal after installing):

   uvx --version

1. Optional — test the server (it will sit idle with no output; that is normal for stdio MCP):

   uvx --from git+https://github.com/Zahid-Abbas-Ali-Baig/document-converter --with markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription] document-converter-mcp

Press Ctrl+C to stop.

---

Install in Cursor 🖱️

1. Open Cursor → Settings → MCP (or edit your config file directly).
2. Config file location:

• Windows: %USERPROFILE%\.cursor\mcp.json
• macOS: ~/.cursor/mcp.json
• Linux: ~/.cursor/mcp.json
• Project-only: .cursor/mcp.json in your project folder

1. Add or merge this block inside mcpServers (copy the whole JSON):

{

"mcpServers": { "document-converter": { "command": "uvx", "args": [ "--from", "git+https://github.com/Zahid-Abbas-Ali-Baig/document-converter", "--with", "markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription]", "document-converter-mcp" ] } } }

1. Save the file and restart Cursor (or click Reload next to MCP in settings).
2. Check: Settings → MCP → document-converter should show enabled (green). Tools: convert_to_markdown, preview_markdown.

Cursor one-click install (optional — if manual JSON fails, use this)

1. Open this link in your browser: Add to Cursor
2. Or paste into the browser address bar:

cursor://anysphere.cursor-deeplink/mcp/install?name=document-converter&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJnaXQraHR0cHM6Ly9naXRodWIuY29tL1phaGlkLUFiYmFzLUFsaS1CYWlnL2RvY3VtZW50LWNvbnZlcnRlciIsIi0td2l0aCIsIm1hcmtpdGRvd25bcGRmLGRvY3gscHB0eCx4bHN4LHhscyxvdXRsb29rLGF1ZGlvLXRyYW5zY3JpcHRpb24seW91dHViZS10cmFuc2NyaXB0aW9uXSIsImRvY3VtZW50LWNvbnZlcnRlci1tY3AiXX0%3D

1. Click Install in Cursor, then restart if tools do not appear.

---

Install in VS Code 💻

Requires VS Code 1.102+ with built-in MCP support.

Do not paste `vscode://mcp/install?...` anywhere. That link is broken in VS Code and creates servers like my-mcp-server-* with spawn vscode://... ENOENT. Use the JSON below.

Method A — Copy-paste user config (recommended)

1. Ctrl+Shift+P → MCP: Open User Configuration
2. Delete any broken servers where "command" starts with vscode:// (e.g. my-mcp-server-15e7e771).
3. Replace the file contents with (or merge servers into your existing file):

{

"servers": { "document-converter": { "type": "stdio", "command": "uvx", "args": [ "--from", "git+https://github.com/Zahid-Abbas-Ali-Baig/document-converter", "--with", "markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription]", "document-converter-mcp" ] } } }

1. Save, then Ctrl+Shift+P → MCP: List Servers → start document-converter.

If you get `uvx` not found (`ENOENT`): run where uvx (Windows) or which uvx (macOS/Linux) and set "command" to the full path:

"command": "C:\\Users\\YOUR_USER\\.local\\bin\\uvx.exe"

Method B — Open this repo in VS Code

1. git clone https://github.com/Zahid-Abbas-Ali-Baig/document-converter.git
2. File → Open Folder → select document-converter
3. VS Code loads .vscode/mcp.json automatically
4. Ctrl+Shift+P → MCP: List Servers → start document-converter

Method C — Add Server wizard

Ctrl+Shift+P → MCP: Add Server → choose stdio, then enter:

| Arg 5 | `document-converter-