MarkItDown 文件转 Markdown 工具

它是什么

MarkItDown 是微软出品的轻量级 Python 工具，把各种文件转成 Markdown，供大模型和文本分析流程使用。它的 README 说，它会尽量保留重要的结构，包括标题、列表、表格和链接。输出是给文本分析工具读的。README 提醒，如果需要给人看的高保真副本，它可能不是最好的选择。你可以在命令行里运行它，在 Python 里调用它，也可以把它当作 MCP 服务器，让智能体来调用。

1. 你把一个文件、一个网址或一个数据流交给它
2. 对应这种格式的转换器读取内容
3. 标题、列表、表格和链接变成 Markdown
4. 你保存文本，或者交给你的大模型

适合谁

做大模型应用或搜索索引、需要把文档喂进去的开发者，以及想拿到 Office 文件里的文字、又不想给每种格式各写一个解析器的人，适合用它。如果你需要给人看的、忠实还原版面的副本，可以不用它。

用在哪里

制作方的文档写了下面这些途径，工具包里每一种都有一页说明。

• 命令行：用 pip 安装的 markitdown 命令
• Python：MarkItDown 类，带 convert()、convert_local() 和 convert_stream()
• MCP 服务器：markitdown-mcp，支持 STDIO、Streamable HTTP 或 SSE，文档给了 Claude Desktop 的步骤
• Docker：用仓库里的 Dockerfile 构建镜像，通过标准输入喂文件
• Azure：用 Document Intelligence 或 Content Understanding 做云端转换
• 插件：第三方转换器，以及一个用大模型读取图片里文字的插件

README 列出的输入有 PDF、PowerPoint、Word、Excel、图片、音频、HTML、CSV、JSON、XML、ZIP 文件、YouTube 网址和 EPub，后面还写了“等等”。

如何设置

点“获取”会把一个装有 Mindket 安装说明的 zip 压缩包存进你的下载文件夹，上面每条途径都有一页。主要途径是在虚拟环境里用 pip 安装。

1. 建一个虚拟环境并激活它。
2. 安装这个包，带上所有可选格式。
3. 对一个文件运行它，看结果。

python -m venv .venv
source .venv/bin/activate
pip install 'markitdown[all]'

如果只想装部分格式，就把它们写出来。下面这行只装 PDF、Word 和 PowerPoint 的依赖。

pip install 'markitdown[pdf, docx, pptx]'

如何使用

把一个文件交给这个命令。它把 Markdown 写到标准输出，或者写到你用 -o 指定的文件里。它也能从管道读取。

markitdown path-to-file.pdf > document.md
markitdown path-to-file.pdf -o document.md
cat path-to-file.pdf | markitdown

在 Python 里，同样的转换只要四行。

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False) # Set to True to enable plugins
result = md.convert("test.xlsx")
print(result.markdown)

示例

你有一份幻灯片 deck.pptx，想让大模型回答跟它有关的问题。装好包之后，运行：

markitdown deck.pptx -o deck.md

打开 deck.md。README 说 MarkItDown 力求保留标题、列表、表格和链接这类结构，所以这些文字可以直接粘进聊天或索引。想要幻灯片里图片的描述，README 的图片示例会传入一个大模型客户端和一个模型名。

新手与专家

新手：Markdown 是只带少量标记的纯文本，标记用来表示标题、列表和表格。README 说，主流大模型天生就“会说” Markdown，而且 Markdown 的写法很省 token。Office 文件和 PDF 不是纯文本。MarkItDown 读取它们，把文字连同结构写出来。先在命令行里一次转一个文件，看过结果再往上搭东西。

专家：convert() 能接收本地文件、远程 URI 和字节流，所以 README 要你用最窄的那个调用：本地文件用 convert_local()，自己先 requests.get() 之后用 convert_response()，要完全控制就用 convert_stream()。插件通过 markitdown.plugin 入口点和一个 register_converters() 函数来注册转换器。OCR 插件把它的转换器注册在优先级 -1.0，排在优先级 0.0 的内置转换器前面。

Document Intelligence 接受模型 ID、分析附加功能和查询字段。返回结构化字段的模型，会把这些字段放进 YAML 前置内容。Content Understanding 按文件类型选分析器，也可以用 cu_analyzer_id 指定一个。它的 cu_file_types 选项限制哪些格式走云端。

注意事项

README 的对照表把内置转换器的文档转换列为离线，成本列为“Local compute only”。远程 URI 和 YouTube 网址要通过网络获取，README 也没有说音频转录是否离线运行。下面这些选项会扩大它能碰到的范围。

• 你的权限：README 说，MarkItDown 以当前进程的权限做 I/O，就像 open() 或 requests.get()。在不可信的环境里要清理输入。在托管或服务端应用里，要限制文件路径、URI 协议和网络目的地
• MCP 服务器：它没有身份验证，以启动它的用户身份运行。它的工具能读那个用户能读的任何文件，也能从网络取数据。它默认绑定到 localhost，README 说不要把它绑到其他接口上
• 云端和大模型调用：Document Intelligence 和 Content Understanding 是计费的 Azure 调用，会把你的文件发给 Azure。大模型客户端会把图片发给你设置的模型。OCR 插件会发送每一张嵌入的图片，扫描版 PDF 的每一页也会以 300 DPI 渲染成整页图片发送
• 适用范围：输出是给文本分析工具用的。README 说，需要给人看的高保真转换时，它可能不是最好的选择
• 插件：插件默认关闭。MCP 服务器的 Dockerfile 把 MARKITDOWN_ENABLE_PLUGINS 设为 True
• 版本：README 描述的是 main 分支。2026 年 11 月 3 日，MCP 包在 PyPI 上的页面只列出 alpha 版本
• 使用数据：README 没有提到，制作方的 Dockerfile 里设置了 ORT_DISABLE_TELEMETRY=1
• 卸载：README 没有给出卸载步骤。可以删掉你专门为它建的虚拟环境，或者对每个包用 pip 自己的卸载
• 许可证：MIT。LICENSE 文件写的是“Copyright (c) Microsoft Corporation.”微软的商标条款适用于它的名称和标志