MarkItDown 的 MCP 封装单工具convert_to_markdown(uri)让 AI agent 直接调。上一篇博文讲了 MarkItDownPython 库、CLI 手动跑但 LLM 时代真正的痛点是让 Claude、Cursor、Continue 这些 agent 能自己转文件——不是你在终端敲命令是模型在对话里直接调工具拿到 Markdown 后继续做事。MarkItDown-MCP微软同 orgAutoGen 团队出品就是为这一场景准备的把 MarkItDown 包成 MCP server单工具convert_to_markdown(uri)支持 http/https/file/data 四种 URI3 种传输STDIO / Streamable HTTP / SSE一键接入 Claude Desktop 或任何 MCP 兼容客户端。GitHubhttps://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcpMITPyPImarkitdown-mcp实测 0.0.1a7核心依赖mcp 2.x实测 2.2.0 markitdown[all] 0.1.1实测环境Python 3.14 venv / Windows 11 / PowerShell git-bash2026-09 握手 工具调用实跑验证相关教程与核心文献资源链接与本文关系markitdown-mcp READMEhttps://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp三种传输 Docker 命令出处PyPI 包页markitdown-mcp · PyPI版本 依赖清单上篇 MarkItDown 博文https://blog.csdn.net/weixin_40192882/category_12444632本篇的前置——Python 库用法MCP 协议规范What is the Model Context Protocol (MCP)? - Model Context Protocol工具/资源/传输协议Claude Desktop 配置Connect to local MCP servers - Model Context Protocolclaude_desktop_config.json路径指引一、痛点agent 不能自己读文件你让 Claude 把这份 PDF 总结一下agent 通常会让你自己粘贴或读上传文件。但实际工作流是agent 自动拿到一个 URL、本地路径或 data URI应该自己转、自己读、自己答——这正是 MCPModel 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_PLUGINStrue启用第三方插件默认关二、三种传输模式与适用场景markitdown-mcp启动命令在不同传输下不同模式命令适用场景限制STDIO默认markitdown-mcp本地 agentClaude Desktop、Cursor、Cline、Continue仅同机进程可连Streamable HTTPmarkitdown-mcp --http --port 3001远程 agent / 团队共享 / 浏览器调试默认绑 127.0.0.1需认证外网SSE已废弃markitdown-mcp --sse --port 3001老版本 MCP 客户端兼容README 已标 Deprecated: alias for --http2.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 endpointhttp://127.0.0.1:3001/mcpSSE endpointhttp://127.0.0.1:3001/sse适合(a) 多 agent 共享一个 server(b) 用 MCP Inspector 调试(c) 在 Docker / WSL / 远程机器上跑。实测2026-09--http --port 3001启动后 uvicorn 日志StreamableHTTP session manager startedGET /mcp→ 200GET /sse→ 200POST /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 路线的命令逐字来自官方 README2026-09 核对原文本机无 Docker 环境未实跑纯 pip 路线2.1 / 2.2 节已全部实测通过。3.2 编辑claude_desktop_config.jsonmacOS~/Library/Application Support/Claude/claude_desktop_config.jsonWindows%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.pdfagent 调用convert_to_markdown(file:///workdir/example.pdf)即可。3.3 重启 Claude Desktop改完配置必须重启 Claude Desktop不是关闭重开而是任务栏图标右键 → Quit → 再启动。新工具会出现在对话界面可调用列表。四、调试MCP Inspector不论哪种传输npx modelcontextprotocol/inspector是官方调试器。4.1 调试 STDIOnpx modelcontextprotocol/inspector浏览器开http://localhost:5173/Transport 选 STDIOCommand 填markitdown-mcp点 Connect → Tools → List Tools → 选convert_to_markdown→ 输入 URI 测试。4.2 调试 HTTP先起 servermarkitdown-mcp --http --port 3001Inspector 选 Streamable HTTPURL 填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(commandmarkitdown-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 venvcommand换成 venv 里markitdown-mcp.exe的绝对路径即可。5.4 多 agent 共享 serverHTTP 模式在一台机器起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.docxPOSIX 路径或反斜杠会报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 模式是无状态 JSONstateless_httpTrue每次 POST 独立完成调用客户端不用管Mcp-Session-Id续接脚本 curl 直接调很方便。六、与其他 MCP 文件读取工具对比MCP server擅长协议格式适用场景markitdown-mcp多格式 → Markdown单工具 convert_to_markdown通用 LLM 喂料filesystem MCP文件 CRUDread_file/write_file/list_directoryagent 编辑文件git MCPgit 操作git_status/commit/diff仓库管理fetch MCPHTTP GETfetch(url)纯网页抓取markitdown-mcp的独特定位只管格式→Markdown这一件事做得最专业。展望MARKITDOWN_ENABLE_PLUGINS已实装但 README 没列可用插件清单——第三方markitdown-ocr等是否注册成 entry_point 待确认HTTP 模式无认证仍是最大短板企业用户需自建反向代理加 auth未来或整合 markitdown-ocr到默认 server 镜像让扫描 PDF 也能开箱即用MCP 2.x SDK2.1.1server 用MCPServermcp.tool()装饰器老 MCP 1.x SDK 的ServerAPI 不兼容。系列导航专栏全集Agent智能体系列更多专栏蛋白 / 多肽分子模拟 / 动力学分子对接 / CADD / 工具其他开源蛋白结构推理预测分子模拟基础UCSF DOCK系列agent智能体系列开源蛋白生成方法实践分子动力学模拟-AmberrDock系列化学大模型介绍2025蛋白药物设计-原理与案例剖析分子动力学模拟-GromacsLeDock系列我胡师兄说药开源多肽设计模型和方法实践結合自由能CADD中的机器学习模型siRNA药物设计模型开源多肽性质预测高效计算基本配置小分子药物设计-原理与案例剖析ASO药物设计模型多肽药物设计-原理与案例剖析作用于DNA/RNA的药物设计实践开源小分子生成和设计实践开源药代动力学模拟软件
MarkItDown-MCP: 把任意格式文件交给Agent一次转 Markdown——3 种传输 + Docker 接入实战
MarkItDown 的 MCP 封装单工具convert_to_markdown(uri)让 AI agent 直接调。上一篇博文讲了 MarkItDownPython 库、CLI 手动跑但 LLM 时代真正的痛点是让 Claude、Cursor、Continue 这些 agent 能自己转文件——不是你在终端敲命令是模型在对话里直接调工具拿到 Markdown 后继续做事。MarkItDown-MCP微软同 orgAutoGen 团队出品就是为这一场景准备的把 MarkItDown 包成 MCP server单工具convert_to_markdown(uri)支持 http/https/file/data 四种 URI3 种传输STDIO / Streamable HTTP / SSE一键接入 Claude Desktop 或任何 MCP 兼容客户端。GitHubhttps://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcpMITPyPImarkitdown-mcp实测 0.0.1a7核心依赖mcp 2.x实测 2.2.0 markitdown[all] 0.1.1实测环境Python 3.14 venv / Windows 11 / PowerShell git-bash2026-09 握手 工具调用实跑验证相关教程与核心文献资源链接与本文关系markitdown-mcp READMEhttps://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp三种传输 Docker 命令出处PyPI 包页markitdown-mcp · PyPI版本 依赖清单上篇 MarkItDown 博文https://blog.csdn.net/weixin_40192882/category_12444632本篇的前置——Python 库用法MCP 协议规范What is the Model Context Protocol (MCP)? - Model Context Protocol工具/资源/传输协议Claude Desktop 配置Connect to local MCP servers - Model Context Protocolclaude_desktop_config.json路径指引一、痛点agent 不能自己读文件你让 Claude 把这份 PDF 总结一下agent 通常会让你自己粘贴或读上传文件。但实际工作流是agent 自动拿到一个 URL、本地路径或 data URI应该自己转、自己读、自己答——这正是 MCPModel 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_PLUGINStrue启用第三方插件默认关二、三种传输模式与适用场景markitdown-mcp启动命令在不同传输下不同模式命令适用场景限制STDIO默认markitdown-mcp本地 agentClaude Desktop、Cursor、Cline、Continue仅同机进程可连Streamable HTTPmarkitdown-mcp --http --port 3001远程 agent / 团队共享 / 浏览器调试默认绑 127.0.0.1需认证外网SSE已废弃markitdown-mcp --sse --port 3001老版本 MCP 客户端兼容README 已标 Deprecated: alias for --http2.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 endpointhttp://127.0.0.1:3001/mcpSSE endpointhttp://127.0.0.1:3001/sse适合(a) 多 agent 共享一个 server(b) 用 MCP Inspector 调试(c) 在 Docker / WSL / 远程机器上跑。实测2026-09--http --port 3001启动后 uvicorn 日志StreamableHTTP session manager startedGET /mcp→ 200GET /sse→ 200POST /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 路线的命令逐字来自官方 README2026-09 核对原文本机无 Docker 环境未实跑纯 pip 路线2.1 / 2.2 节已全部实测通过。3.2 编辑claude_desktop_config.jsonmacOS~/Library/Application Support/Claude/claude_desktop_config.jsonWindows%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.pdfagent 调用convert_to_markdown(file:///workdir/example.pdf)即可。3.3 重启 Claude Desktop改完配置必须重启 Claude Desktop不是关闭重开而是任务栏图标右键 → Quit → 再启动。新工具会出现在对话界面可调用列表。四、调试MCP Inspector不论哪种传输npx modelcontextprotocol/inspector是官方调试器。4.1 调试 STDIOnpx modelcontextprotocol/inspector浏览器开http://localhost:5173/Transport 选 STDIOCommand 填markitdown-mcp点 Connect → Tools → List Tools → 选convert_to_markdown→ 输入 URI 测试。4.2 调试 HTTP先起 servermarkitdown-mcp --http --port 3001Inspector 选 Streamable HTTPURL 填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(commandmarkitdown-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 venvcommand换成 venv 里markitdown-mcp.exe的绝对路径即可。5.4 多 agent 共享 serverHTTP 模式在一台机器起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.docxPOSIX 路径或反斜杠会报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 模式是无状态 JSONstateless_httpTrue每次 POST 独立完成调用客户端不用管Mcp-Session-Id续接脚本 curl 直接调很方便。六、与其他 MCP 文件读取工具对比MCP server擅长协议格式适用场景markitdown-mcp多格式 → Markdown单工具 convert_to_markdown通用 LLM 喂料filesystem MCP文件 CRUDread_file/write_file/list_directoryagent 编辑文件git MCPgit 操作git_status/commit/diff仓库管理fetch MCPHTTP GETfetch(url)纯网页抓取markitdown-mcp的独特定位只管格式→Markdown这一件事做得最专业。展望MARKITDOWN_ENABLE_PLUGINS已实装但 README 没列可用插件清单——第三方markitdown-ocr等是否注册成 entry_point 待确认HTTP 模式无认证仍是最大短板企业用户需自建反向代理加 auth未来或整合 markitdown-ocr到默认 server 镜像让扫描 PDF 也能开箱即用MCP 2.x SDK2.1.1server 用MCPServermcp.tool()装饰器老 MCP 1.x SDK 的ServerAPI 不兼容。系列导航专栏全集Agent智能体系列更多专栏蛋白 / 多肽分子模拟 / 动力学分子对接 / CADD / 工具其他开源蛋白结构推理预测分子模拟基础UCSF DOCK系列agent智能体系列开源蛋白生成方法实践分子动力学模拟-AmberrDock系列化学大模型介绍2025蛋白药物设计-原理与案例剖析分子动力学模拟-GromacsLeDock系列我胡师兄说药开源多肽设计模型和方法实践結合自由能CADD中的机器学习模型siRNA药物设计模型开源多肽性质预测高效计算基本配置小分子药物设计-原理与案例剖析ASO药物设计模型多肽药物设计-原理与案例剖析作用于DNA/RNA的药物设计实践开源小分子生成和设计实践开源药代动力学模拟软件
