MarkItDown 的 MCP 封装，单工具convert_to_markdown(uri)，让 AI agent 直接调。

上一篇博文讲了 MarkItDown（Python 库、CLI 手动跑），但 LLM 时代真正的痛点是：让 Claude、Cursor、Continue 这些 agent 能"自己"转文件——不是你在终端敲命令，是模型在对话里直接调工具，拿到 Markdown 后继续做事。MarkItDown-MCP（微软同 org，AutoGen 团队出品）就是为这一场景准备的：把 MarkItDown 包成 MCP server，单工具convert_to_markdown(uri)支持 http/https/file/data 四种 URI，3 种传输（STDIO / Streamable HTTP / SSE），一键接入 Claude Desktop 或任何 MCP 兼容客户端。

GitHub：https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp（MIT）
PyPI：markitdown-mcp（实测 0.0.1a7）
核心依赖：mcp 2.x（实测 2.2.0）+ markitdown[all] >= 0.1.1
实测环境：Python 3.14 venv / Windows 11 / PowerShell + git-bash（2026-09 握手 + 工具调用实跑验证）

相关教程与核心文献

一、痛点：agent 不能"自己"读文件

你让 Claude "把这份 PDF 总结一下"，agent 通常会让你自己粘贴或读上传文件。但实际工作流是：agent 自动拿到一个 URL、本地路径或 data URI，应该自己转、自己读、自己答——这正是 MCP（Model Context Protocol）的设计目标。

MarkItDown-MCP 把这种"转文件"能力封装成一个标准 MCP 工具：

工具名: convert_to_markdown 参数: uri: str ← http/https/file/data 四种 URI 都行 返回: str ← 转换后的 Markdown

核心特点：

• 单工具：不像有些 MCP server 暴露一桌，MarkItDown-MCP 只暴露convert_to_markdown一个——简单到模型调用 0 误触（实测tools/list返回就这一个，inputSchema只有uri: str必填参数）；
• URI 直通：http(s) 远程、file 本地、data base64 都支持，等价于把 MarkItDown 的convert_uri(...)包装出来；
• 插件可选：环境变量MARKITDOWN_ENABLE_PLUGINS=true启用第三方插件（默认关）；

二、三种传输模式与适用场景

markitdown-mcp启动命令在不同传输下不同：

2.1 STDIO（最常用）

pip install markitdown-mcp markitdown-mcp

直接前台启动，agent 客户端通过 stdin/stdout 与 server 通信。这是 Claude Desktop / Cursor 默认推荐的方式——客户端 spawn 子进程，自动管理生命周期。

实测（2026-09）：往 stdin 连发initialize→notifications/initialized→tools/list→tools/call四段 JSON-RPC，握手返回protocolVersion: 2025-03-26、serverInfo: {"name": "markitdown"}，convert_to_markdown("file:///C:/.../test.docx")正确返回 Markdown——STDIO 链路全通。

2.2 Streamable HTTP / SSE（远程或调试）

markitdown-mcp --http --host 127.0.0.1 --port 3001

启动后：

• Streamable HTTP endpoint：http://127.0.0.1:3001/mcp
• SSE endpoint：http://127.0.0.1:3001/sse

适合：(a) 多 agent 共享一个 server；(b) 用 MCP Inspector 调试；(c) 在 Docker / WSL / 远程机器上跑。

实测（2026-09）：--http --port 3001启动后 uvicorn 日志StreamableHTTP session manager started；GET /mcp→ 200，GET /sse→ 200；POST /mcp发initialize和tools/call（转 xlsx）均 200 返回正确 JSON。另外两条边界行为也实测了：(1)markitdown-mcp --port 3002不加--http会直接报错退出（"Host and port arguments are only valid when using streamable HTTP or SSE transport"）；(2)--sse确实只是--http的别名，同一服务同时挂/mcp和/sse两个端点。

2.3 安全警告（README 反复强调）

• HTTP 模式默认绑127.0.0.1——同机访问 OK，不要绑 0.0.0.0 或公网 IP；
• 启动时若 host 非 localhost，会打印 5 行 WARNING（无密码 + 用当前用户权限 + 任何能连的人都可读你的文件 + 取网络资源）；
• server无认证机制，需要 sandbox（容器 / VM）隔离；
• convert_to_markdown工具可读 server 用户能读的所有文件 + 所有网络可达资源——敏感环境必装 Docker / 限制目录 mount。

三、Claude Desktop 接入（Docker 推荐）

README 建议 Docker 启动而非 pip 直装——理由是隔离 + 跨平台一致。

3.1 构建镜像

git clone https://github.com/microsoft/markitdown.git cd markitdown/packages/markitdown-mcp docker build -t markitdown-mcp:latest .

注：Docker 路线的命令逐字来自官方 README（2026-09 核对原文），本机无 Docker 环境未实跑；纯 pip 路线（2.1 / 2.2 节）已全部实测通过。

3.2 编辑claude_desktop_config.json

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

最小配置（仅远程 URI）：

{ "mcpServers": { "markitdown": { "command": "docker", "args": ["run", "--rm", "-i", "markitdown-mcp:latest"] } } }

需要读本地文件（挂载工作目录）：

{ "mcpServers": { "markitdown": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "C:/Users/<USER>/data:/workdir", "markitdown-mcp:latest" ] } } }

挂载后，本地C:/Users/<USER>/data/example.pdf在容器内路径为/workdir/example.pdf，agent 调用convert_to_markdown("file:///workdir/example.pdf")即可。

3.3 重启 Claude Desktop

改完配置必须重启 Claude Desktop（不是关闭重开，而是任务栏图标右键 → Quit → 再启动）。新工具会出现在对话界面可调用列表。

四、调试：MCP Inspector

不论哪种传输，npx @modelcontextprotocol/inspector是官方调试器。

4.1 调试 STDIO

npx @modelcontextprotocol/inspector

浏览器开http://localhost:5173/，Transport 选 STDIO，Command 填markitdown-mcp，点 Connect → Tools → List Tools → 选convert_to_markdown→ 输入 URI 测试。

4.2 调试 HTTP

先起 server：

markitdown-mcp --http --port 3001

Inspector 选 Streamable HTTP，URL 填http://127.0.0.1:3001/mcp，连上后测试。

五、4 个实战用例

5.1 Claude Desktop 读远程 PDF

直接在对话里说："帮我读一下这篇论文 https://example.com/paper.pdf 并总结"——agent 自动调convert_to_markdown("https://example.com/paper.pdf")，拿到 Markdown 后基于内容回答。

5.2 Cursor 读本地 PPT

挂载工作目录后，对话里说："总结我桌面上的 slides.pptx"——agent 调convert_to_markdown("file:///workdir/slides.pptx")。

5.3 RAG 数据预处理

脚本里写：

import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def convert(uri): params = StdioServerParameters(command="markitdown-mcp") async with stdio_client(params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() result = await session.call_tool("convert_to_markdown", {"uri": uri}) return result.content[0].text md = asyncio.run(convert("https://example.com/paper.pdf")) open("paper.md", "w").write(md)

这段客户端代码在 mcp 2.2.0 上实测原样跑通（Windows venv，command换成 venv 里markitdown-mcp.exe的绝对路径即可）。

5.4 多 agent 共享 server（HTTP 模式）

在一台机器起markitdown-mcp --http --port 3001，其他机器的 agent 客户端通过http://192.168.x.x:3001/mcp接入——前提是网络可达 + 你接受无认证风险。

5.5 实测踩坑（Windows 必读）

• file URI 必须正斜杠 + 盘符全路径：file:///C:/Users/.../test.docx才认；写成file:///tmp/test.docx（POSIX 路径）或反斜杠会报Could not read the resource: No such file or directory。git-bash 里可用cygpath -m /tmp/test.docx生成正斜杠 Windows 路径再拼 URI；
• --port/--host是--http的附属参数：单独用会启动失败（实测报错退出，见 2.2 节）；
• HTTP 模式是无状态 JSON（stateless_http=True）：每次 POST 独立完成调用，客户端不用管Mcp-Session-Id续接，脚本 curl 直接调很方便。

六、与其他 MCP 文件读取工具对比

markitdown-mcp的独特定位：只管"格式→Markdown"这一件事，做得最专业。

展望

• MARKITDOWN_ENABLE_PLUGINS已实装，但 README 没列可用插件清单——第三方markitdown-ocr等是否注册成 entry_point 待确认；
• HTTP 模式无认证仍是最大短板，企业用户需自建反向代理加 auth；
• 未来或整合 markitdown-ocr到默认 server 镜像，让扫描 PDF 也能开箱即用；
• MCP 2.x SDK（>=2.1.1）：server 用MCPServer+@mcp.tool()装饰器，老 MCP 1.x SDK 的ServerAPI 不兼容。

系列导航：专栏全集Agent智能体系列

更多专栏：