工作流
MarkItDown
微软的 Python 工具,把办公文档转成 Markdown,方便交给模型或代理使用。
microsoft/markitdown 用 MIT 许可发布,是一个把常见办公文件转成 Markdown 的 Python 工具。它的用途很直接:先把文档变成纯文本结构,再交给模型或编码代理处理,而不是让模型去“看”一个二进制文件。
适合已经要用代理读合同、幻灯片或技术文档的人。先在一小份你有权处理的文件上试转换结果,再接入工作流。转换后的文本仍受原文件版权约束,不要把别人的文档转完再公开发表。
推荐来源:
- @0x_rody 在 2026 年 11 月 14 日 的帖子里提到了这个项目(数字采集于 2026 年 11 月 15 日:26 次喜欢,0 次转发)。
本页是导读,不是原文。
解决什么问题
MarkItDown(仓库 microsoft/markitdown)是微软的 Python 工具,用来把常见办公文件转成 Markdown,方便交给模型或编码代理处理。它强调保留标题、列表、表格和链接这类结构,官方也说明:输出往往可供人阅读,但目标仍是给文本分析工具用,不一定适合高精度的人工排版转换。
仓库另外提供官方 MCP 包 markitdown-mcp。它暴露一个工具 convert_to_markdown(uri),可处理 http:、https:、file: 或 data: URI。本文同时写命令行、Python API 和这条官方 MCP 用法。
适合谁
适合需要让代理阅读 PDF、Word、PowerPoint、Excel 或其他已有权处理的文件的人。项目使用 MIT 许可。前提是 Python 3.10 到 3.14。官方建议在虚拟环境中安装,以免依赖冲突。
转换后的文本仍受原文件版权约束,不要把别人的文档转完再公开发表。先在一小份你有权处理的文件上查看效果,再接入工作流。
怎么装
核验日期为 2026-11-15(Asia/Shanghai)。命令来自仓库 README 和官方 MCP 包说明 packages/markitdown-mcp/README.md。
命令行和 Python
推荐先安装带全部可选依赖的版本:
python -m venv .venv
source .venv/bin/activate
pip install 'markitdown[all]'若只用部分格式,也可以按需安装,例如 pip install 'markitdown[pdf, docx, pptx]'。官方列出的可选依赖包括 pptx、docx、xlsx、xls、pdf、outlook,以及 Azure Document Intelligence、Azure Content Understanding、音频转写和 YouTube 转写等。
命令行基本用法:
markitdown path-to-file.pdf -o document.md也可以把文件通过管道交给它:cat path-to-file.pdf | markitdown。在 Python 里:
from markitdown import MarkItDown
md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")
print(result.markdown)插件默认关闭。若要给图片生成说明,官方目前写明主要用于 pptx 和图片文件,并需要你提供 llm_client 和 llm_model。图片说明、语音转写以及两条 Azure 云服务都会访问托管服务;若必须完全本地运行,只安装你确实要使用的可选依赖。
MCP
pip install markitdown-mcp
markitdown-mcp默认是 STDIO。若改用 Streamable HTTP 和 SSE,官方命令是:
markitdown-mcp --http --host 127.0.0.1 --port 3001官方强调:这个 MCP 包是给本机、受信任的代理用的。HTTP / SSE 默认绑定 localhost。不要在未理解安全后果的情况下绑定到其他网卡。服务器没有认证,并以启动它的用户权限运行;convert_to_markdown 可以读取该用户能访问的文件或网络数据。
对 Claude Desktop,官方建议用 Docker 镜像,并给出如下配置:
{
"mcpServers": {
"markitdown": {
"command": "docker",
"args": ["run", "--rm", "-i", "markitdown-mcp:latest"]
}
}
}若要转换本机文件,需要按 MCP README 把目录挂进容器,例如挂到 /workdir。仓库根 README 没有给出 Cursor 或 Claude Code 的现成命令;其他 MCP 客户端若支持标准 stdio 启动方式,可以使用 markitdown-mcp 命令,但本文不编造未经官方写出的客户端片段。
一个实际例子
下面的步骤是为本文写的核验流程,不是官方固定口令。本次没有实跑,因此不编造转换后的 Markdown。
- 准备一份你有权处理的短 PDF,放在当前目录,例如
sample.pdf。 - 在已激活的虚拟环境中执行:
markitdown sample.pdf -o sample.md- 打开
sample.md,检查标题、列表和表格是否还在,有没有明显切断的句子。官方说明它不是为高精度人工排版而设计的;issue #2370(2026-11-15 仍为 open)就报告过 PDF 段落被打断的情况。 - 若通过 MCP 使用,向客户端发送:
Convert file:///absolute/path/to/sample.pdf to Markdown with convert_to_markdown. Do not fetch any other URI.然后对照你在命令行得到的结果,而不是假设两者完全一致。
常见坑
- 只安装了核心包,却去转 PDF 或 Office 文件。这些格式依赖可选 extras。若转换失败,先确认安装的是
markitdown[all]还是你实际用到的那一组 extras。 - 把
convert()用在不可信输入上。官方安全节写明,MarkItDown 以当前进程的权限做 I/O,行为类似open()或requests.get()。若只处理本地文件,应改用更窄的convert_local();若要自己控制下载,先自行请求再调用convert_response()或convert_stream()。 - 把 MCP 服务器绑到非本地地址。官方 MCP README 反复提醒:默认只绑
localhost,且没有认证。同机上的其他进程也能访问它。 - 以为转换结果可以随便公开发布。转换只改变格式,不改变原作的权利。也不要把含有密钥或未公开合同的文件交给不可信的环境。
FAQ
必须安装全部可选依赖吗?
不是。markitdown[all] 最省事,但你也可以只装要用的 extras,例如 pdf 和 docx。少装一些依赖,也有助于避免无意中启用会访问网络的功能。
MCP 和命令行会得到同一份结果吗?
官方 MCP 包调用的是同一个 MarkItDown 库,工具是 convert_to_markdown(uri)。本文没有并排实跑两种入口,因此不保证输出完全一致。若结果不同,先核对 URI、插件开关和可选依赖是否相同。
可以用来转网页或 YouTube 吗?
README 把 HTML 和 YouTube URL 列入支持范围;YouTube 转写属于可选依赖,并且会用到托管服务。本文没有实跑这些来源。对远程 URI 仍要遵守官方的输入清理建议,不要把代理指向你不打算访问的地址。
Claude Desktop 一定要用 Docker 吗?
官方 MCP README 写的是:在 Claude Desktop 上推荐使用 Docker 镜像,并给出了相应的 claude_desktop_config.json 示例。它没有把本机 markitdown-mcp 命令写成 Claude Desktop 的推荐配置。
它能替代专业 OCR 或排版工具吗?
官方把目标定位为给 LLM 和文本分析管道使用,而不是高精度的人工阅读转换。扫描件、复杂表格或需要结构化字段的场景,README 指向 Azure Document Intelligence 或 Azure Content Understanding,那些是单独的云服务,有自己的密钥和计费。
来源与许可
仓库 microsoft/markitdown 及其 MCP 包使用 MIT 许可。本文依据 2026-11-15 查阅的根目录 README 和 markitdown-mcp README,用自己的话写成,供 CQBase 上下文库使用。若安装命令、Python 版本或 MCP 绑定方式有变,以这些官方材料为准。