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

[MIT License] [Python 3.10+] [MCP Registry]

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 (includes uvx).

   Windows (PowerShell):

   powershell

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

   macOS / Linux:

   bash

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

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

   bash

   uvx --version

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

   bash

   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
3. 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"      ]    }  }}

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

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

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"      ]    }  }}

4. 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:

Install in Claude Desktop 🤖

1. Open Claude Desktop config:

   • Windows (Microsoft Store): %LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\claude_desktop_config.json
   • Windows (classic): %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   On Windows Store Claude, %APPDATA%\Claude\ may not exist — use the Packages\Claude_*\... path above.

2. Windows (Microsoft Store) — one-time setup so uvx --from git+... can find Git (Claude passes a minimal PATH to MCP servers):

   powershell

   powershell -ExecutionPolicy Bypass -File scripts/setup-windows-uvx-git-shim.ps1

   Or download and run that script from the repo. It creates %USERPROFILE%\.local\bin\git.cmd pointing at Git for Windows.

3. Add inside mcpServers (keep existing preferences at the root):

{  "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"      ]    }  }}

If you get uvx not found (ENOENT): set "command" to the full path from where uvx, e.g. C:\\Users\\YOUR_USER\\.local\\bin\\uvx.exe.

4. Restart Claude Desktop completely (quit from tray, reopen).

Verify it works ✅

Ask your AI assistant:

List the tools from document-converter MCP.

Or:

Preview markdown for a PDF on my machine at C:\path\to\file.pdf

You should see convert_to_markdown and preview_markdown being called.

Tools 🛠️

Input: absolute or relative path to a file on your machine (or a supported URL for YouTube).

Output: Markdown text suitable for summarization, diffing, or committing to Git.

Usage examples 💬

Natural-language prompts you can paste into Cursor, VS Code, or Claude Desktop after the MCP server is connected.

Convert a PDF and summarize

Prompt:

Use document-converter to convert C:\Reports\annual-report.pdf to markdown,then give me a 5-bullet executive summary.

What happens: The agent calls convert_to_markdown, creates annual-report.md next to the PDF, and summarizes the result.

Preview a Word doc before saving

Prompt:

Preview markdown for ./contracts/vendor-agreement.docx without saving.Tell me if there is a termination clause.

What happens: The agent calls preview_markdown, reads the content in chat, and answers your question — no file is written.

Excel to analysis

Prompt:

Convert D:\data\sales-q1.xlsx to markdown and list the top 3 products by revenue.

What happens: Spreadsheet tables become Markdown the model can parse and rank.

PowerPoint for release notes

Prompt:

Preview ./slides/product-launch.pptx as markdown and draft release notesfrom the slide titles and bullet points.

Outlook email extraction

Prompt:

Convert C:\Mail\customer-escalation.msg to markdown and extract action items.

Batch-style workflow (multiple files)

Prompt:

Convert these to markdown and save beside each file:- C:\Docs\spec-v2.pdf- C:\Docs\api-reference.docx- C:\Docs\metrics.xlsxThen confirm the .md paths.

Audio transcription

Prompt:

Preview markdown for ./recordings/standup-notes.mp3 and list decisions made.

Requires the audio-transcription extra (included in this project's dependencies).

YouTube URL

Prompt (preview in chat):

Use preview_markdown on https://www.youtube.com/watch?v=EXAMPLE and summarize the main points.

Prompt (save to file):

Use convert_to_markdown on https://www.youtube.com/watch?v=EXAMPLE

What happens: MarkItDown fetches the watch page, extracts title/description/metadata, and appends captions via youtube-transcript-api when available. convert_to_markdown saves youtube-EXAMPLE.md in the server working directory.

Use https://www.youtube.com/watch?v=... format. Requires the youtube-transcription extra and an internet connection.

Example Markdown output (PDF)

Illustrative snippet after conversion:

# Quarterly Results
Revenue increased 12% year over year driven by enterprise subscriptions.
## Highlights
- Net retention: 118%- New logos: 240- Gross margin: 74%

Quality depends on the source document layout and MarkItDown version.

Local development 🧪

Clone if you prefer a local virtual environment over uvx.

git clone https://github.com/Zahid-Abbas-Ali-Baig/document-converter.gitcd document-converterpython -m venv .venv

Windows (PowerShell):

.venv\Scripts\activatepip install -r requirements.txt

macOS / Linux:

source .venv/bin/activatepip install -r requirements.txt

Run the server directly (stdio — used by MCP clients):

python server.py

Configuration reference ⚙️

All clients run the same underlying command (full JSON examples are in Quick install 🚀 — not repeated here):

Config file locations

Copy-paste configs: Quick install 🚀.

Local clone (no uvx)

Clone and install — see Local development 🧪. Then point your MCP client at the venv Python:

Windows:

{  "mcpServers": {    "document-converter": {      "command": "REPO_PATH\\.venv\\Scripts\\python.exe",      "args": ["REPO_PATH\\server.py"]    }  }}

macOS / Linux:

{  "mcpServers": {    "document-converter": {      "command": "REPO_PATH/.venv/bin/python",      "args": ["REPO_PATH/server.py"]    }  }}

MCP Registry 📦

Listed on the official MCP Registry as io.github.Zahid-Abbas-Ali-Baig/document-converter (v1.0.0).

• 🔍 Registry entry (v1.0.0)
• 📂 GitHub repository
• 📥 GitHub Release v1.0.0 (.mcpb bundle)

Troubleshooting 🔧

Dependency resolution / markitdown[all] errors

If you see errors about azure-ai-contentunderstanding or pre-releases, remove markitdown[all] from your config. Use:

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

VS Code: spawn vscode://mcp/install?... ENOENT

VS Code's install link wrote the URL as the command instead of uvx. Fix:

1. MCP: Open User Configuration (or .vscode/mcp.json in this repo)
2. Delete entries like my-mcp-server-* where "command" starts with vscode://
3. Use .vscode/mcp.json from this repo, or the JSON in Install in VS Code 💻
4. MCP: List Servers → restart document-converter

Do not use the README vscode://mcp/install?... link — it is unreliable in VS Code.

Claude Desktop: Git executable not found

uvx --from git+... needs Git on PATH. Microsoft Store Claude on Windows often spawns MCP servers with a minimal PATH that omits C:\Program Files\Git\cmd, even when Git works in a normal terminal.

Fix: run the one-time shim script from Install in Claude Desktop 🤖 (step 2). It places git.cmd next to uvx.exe in %USERPROFILE%\.local\bin.

Also ensure: Git for Windows and uv are installed. Pre-warm in PowerShell: 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 (idle = normal for stdio).

Fallback: Local clone (no uvx) if you cannot use uvx.

Failed to acquire MessagePort

This comes from Cursor or VS Code, not this server:

[MCPService] Error creating client: Failed to acquire MessagePort ...

Reliable fallback: follow Local development 🧪 and use the local clone MCP config.

Install button does nothing (Cursor on Windows)

Use the copy-paste JSON in Install in Cursor 🖱️ instead of the install badge.

Tools not visible

Reload MCP or restart the editor. Confirm the server is enabled (not red/disabled).

License 📜

MIT License — see LICENSE.

Copyright (c) 2026 Zahid Abbas Ali Baig