document-converter

📄 Document Converter MCP

在 Cursor、VS Code 和任何 MCP 客户端中将文档转换为 Markdown。
本地处理 · 不上传到云端 · 由 MarkItDown 提供支持

让你的 AI 助手能够以清晰的 Markdown 格式读取 PDF、Office 文件、电子表格、电子邮件、音频等内容，从而能够对内容进行摘要、搜索和推理，而不必费力处理二进制附件。

目录

• 概述 📋
• 使用场景 💡
• 功能 ✨
• 支持的格式 📎
• 快速安装 🚀
  • 开始之前
  • Cursor 🖱️
  • VS Code 💻
  • Claude Desktop 🤖
  • 验证是否正常运行 ✅
• 工具 🛠️
• 使用示例 💬
• 本地开发 🧪
• 配置参考 ⚙️
• MCP 注册表 📦
• 故障排除 🔧
• 许可证 📜

概述 📋

Document Converter MCP 是一个轻量级的 stdio 服务，它封装了 Microsoft 的 MarkItDown 库，用于 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]

连接后，你的 Agent 会在本地转换文件并返回结构化文本——不会向转换 API 发送任何内容。

使用场景 💡

功能 ✨

• 🏠 本地优先 — 文件留在你的设备上；不使用第三方转换服务
• 📎 支持多种格式 — PDF、Office、CSV/JSON/文本、Outlook .msg、音频、YouTube 等（通过 MarkItDown）
• 🔀 两种工作流 — 将 Markdown 保存到源文件旁，或仅在聊天中预览
• 📋 复制粘贴即可设置 — 为 Cursor、VS Code 和 Claude Desktop 提供分步安装说明
• 📦 已发布到注册表 — 已列入官方 MCP 注册表
• ⚖️ MIT 许可 — 可免费用于个人和商业用途

支持的格式 📎

以下格式已通过 MarkItDown 0.1.6 验证，测试时安装了以下额外依赖：

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

我们不会使用 markitdown[all]，因为它会引入 Azure 预发布软件包，导致 uv 无法通过 uvx 解析依赖。

完全支持（使用本项目的依赖项）

有限支持

不支持

转换质量取决于源文件。上游详情请参阅 MarkItDown 文档。

快速安装 🚀

请按照适用于你所用编辑器的步骤操作。以下所有配置使用相同的命令 — 只有 JSON 文件和封装键不同。

开始之前（所有编辑器）

1. 安装 uv（包含 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
   

2. 验证 uvx 是否正常运行（安装后打开一个新终端）：

   uvx --version
   

3. 可选 — 测试服务（它会保持空闲且不输出内容；对于 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
   

   按 Ctrl+C 停止。

在 Cursor 中安装 🖱️

1. 打开 Cursor → Settings → MCP（或直接编辑配置文件）。
2. 配置文件位置：
   • Windows： %USERPROFILE%\.cursor\mcp.json
   • macOS： ~/.cursor/mcp.json
   • Linux： ~/.cursor/mcp.json
   • 仅限项目： 项目文件夹中的 .cursor/mcp.json
3. 在 mcpServers 中添加或合并此代码块（复制整个 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. 保存文件并重启 Cursor（或点击设置中 MCP 旁边的 Reload）。
5. 检查： Settings → MCP → document-converter 应显示为已启用（绿色）。工具：convert_to_markdown、preview_markdown。

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

在 VS Code 中安装 💻

需要 VS Code 1.102+，并启用内置 MCP 支持。

请勿在任何位置粘贴 vscode://mcp/install?...。 该链接在 VS Code 中无法使用，并会创建名称类似 my-mcp-server-* 的服务，导致 spawn vscode://... ENOENT。请使用下面的 JSON。

方法 A — 复制并粘贴用户配置（推荐）

1. Ctrl+Shift+P → MCP: Open User Configuration
2. 删除所有 "command" 以 vscode:// 开头的故障服务（例如 my-mcp-server-15e7e771）。
3. 将文件内容替换为（或将 servers 合并到现有文件中）：

{
  "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. 保存，然后按 Ctrl+Shift+P → MCP: List Servers → 启动 document-converter。

**如果出现找不到 uvx（ENOENT）：**运行 where uvx（Windows）或 which uvx（macOS/Linux），并将 "command" 设置为完整路径：

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

方法 B — 在 VS Code 中打开此仓库

1. git clone https://github.com/Zahid-Abbas-Ali-Baig/document-converter.git
2. File → Open Folder → 选择 document-converter
3. VS Code 会自动加载 .vscode/mcp.json
4. 按 Ctrl+Shift+P → MCP: List Servers → 启动 document-converter

方法 C — 使用添加服务向导

按 Ctrl+Shift+P → MCP: Add Server → 选择 stdio，然后输入：

在 Claude Desktop 中安装 🤖

1. 打开 Claude Desktop 配置文件：

   • Windows（Microsoft Store）： %LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\claude_desktop_config.json
   • Windows（经典版）： %APPDATA%\Claude\claude_desktop_config.json
   • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

   在 Windows Store 版 Claude 中，%APPDATA%\Claude\ 可能不存在——请使用上面的 Packages\Claude_*\... 路径。

2. Windows（Microsoft Store）——一次性设置，让 uvx --from git+... 能找到 Git（Claude 传递给 MCP 服务的 PATH 是精简版）：

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

   或从仓库下载并运行该脚本。它会创建 %USERPROFILE%\.local\bin\git.cmd，指向 Git for Windows。

3. 在 mcpServers 中添加（保留根级别已有的 preferences）：

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

如果提示找不到 uvx（ENOENT）： 将 "command" 设置为 where uvx 返回的完整路径，例如 C:\\Users\\YOUR_USER\\.local\\bin\\uvx.exe。

4. 完全重启 Claude Desktop（从系统托盘退出，然后重新打开）。

验证是否正常 ✅

向你的 AI 助手提问：

List the tools from document-converter MCP.

或者：

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

你应该会看到 convert_to_markdown 和 preview_markdown 被调用。

工具 🛠️

输入： 你机器上文件的绝对或相对路径（或受支持的 YouTube URL）。

输出： 适用于摘要、差异比较或提交到 Git 的 Markdown 文本。

使用示例 💬

MCP 服务连接后，可粘贴到 Cursor、VS Code 或 Claude Desktop 中的自然语言提示词。

转换 PDF 并总结

提示词：

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

执行结果： Agent 调用 convert_to_markdown，在 PDF 旁创建 annual-report.md，并总结转换结果。

保存前预览 Word 文档

提示词：

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

执行结果： Agent 调用 preview_markdown，在聊天中读取内容并回答你的问题——不会写入文件。

将 Excel 转换为分析内容

提示词：

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

执行结果： 电子表格中的表格会转换为模型能够解析和排序的 Markdown。

用于发布说明的 PowerPoint

提示词：

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

提取 Outlook 邮件

提示词：

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

批量式工作流（多个文件）

提示词：

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

音频转录

提示词：

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

需要 audio-transcription extra（已包含在本项目的依赖项中）。

YouTube URL

提示词（在聊天中预览）：

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

提示词（保存到文件）：

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

执行结果： MarkItDown 会获取观看页面，提取标题、描述和元数据，并在可用时通过 youtube-transcript-api 附加字幕。convert_to_markdown 会在服务工作目录中保存 youtube-EXAMPLE.md。

请使用 https://www.youtube.com/watch?v=... 格式。需要 youtube-transcription extra 和互联网连接。

Markdown 输出示例（PDF）

转换后的示例片段：

# Quarterly Results

Revenue increased 12% year over year driven by enterprise subscriptions.

## Highlights

- Net retention: 118%
- New logos: 240
- Gross margin: 74%

效果取决于源文档的布局和 MarkItDown 版本。

本地开发 🧪

如果你更倾向于使用本地虚拟环境而不是 uvx，请克隆仓库。

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

Windows（PowerShell）：

.venv\Scripts\activate
pip install -r requirements.txt

macOS / Linux：

source .venv/bin/activate
pip install -r requirements.txt

直接运行服务（stdio——供 MCP 客户端使用）：

python server.py

配置参考 ⚙️

所有客户端都运行相同的底层命令（完整 JSON 示例见快速安装 🚀 — 此处不再重复）：

配置文件位置

复制粘贴配置：快速安装 🚀。

本地克隆（无需 uvx）

克隆并安装 — 请参阅本地开发 🧪。然后将 MCP 客户端指向虚拟环境中的 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 📦

已列入官方 MCP Registry，名称为 io.github.Zahid-Abbas-Ali-Baig/document-converter（v1.0.0）。

• 🔍 Registry 条目（v1.0.0）
• 📂 GitHub 仓库
• 📥 GitHub Release v1.0.0（.mcpb bundle）

故障排除 🔧

依赖解析 / markitdown[all] 错误

如果看到与 azure-ai-contentunderstanding 或预发布版本相关的错误，请从配置中移除 markitdown[all]。请使用：

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

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

VS Code 的安装链接将 URL 设置成了命令，而不是 uvx。修复方法：

1. MCP: Open User Configuration（或此仓库中的 .vscode/mcp.json）
2. 删除 "command" 以 vscode:// 开头的 my-mcp-server-* 等条目
3. 使用此仓库中的 .vscode/mcp.json，或使用在 VS Code 中安装 💻中的 JSON
4. MCP: List Servers → 重启 document-converter

请勿使用 README 中的 vscode://mcp/install?... 链接 — 该链接在 VS Code 中不可靠。

Claude Desktop：Git executable not found

uvx --from git+... 需要将 Git 添加到 PATH。Windows 上通过 Microsoft Store 安装的 Claude 经常以精简的 PATH 启动 MCP 服务，其中不包含 C:\Program Files\Git\cmd，即使 Git 在普通终端中可以正常运行。

修复方法： 运行在 Claude Desktop 中安装 🤖（步骤 2）中的一次性 shim 脚本。它会将 git.cmd 放在 %USERPROFILE%\.local\bin 中，与 uvx.exe 同目录。

另请确保： 已安装 Git for Windows 和 uv。在 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（stdio 模式下处于空闲状态是正常的）。

备用方案： 如果无法使用 uvx，请参阅本地克隆（无需 uvx）。

Failed to acquire MessagePort

此问题来自 Cursor 或 VS Code，与此服务无关：

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

可靠的备用方案： 按照本地开发 🧪操作，并使用本地克隆 MCP 配置。

安装按钮无响应（Windows 上的 Cursor）

请使用在 Cursor 中安装 🖱️中的 JSON 复制并粘贴，而不要使用安装徽章。

工具未显示

重新加载 MCP 或重启编辑器。确认服务已启用（而非显示红色/禁用状态）。

许可证 📜

MIT 许可证 — 参见 LICENSE。

版权所有 (c) 2026 Zahid Abbas Ali Baig