# MarkItDown

Canonical: https://cqbase.net/zh/entry/markitdown
Chinese: https://cqbase.net/zh/entry/markitdown
English: https://cqbase.net/en/entry/markitdown

> 微软的 Python 工具，把办公文档转成 Markdown，方便交给模型或代理使用。

microsoft/markitdown 用 MIT 许可发布，是一个把常见办公文件转成 Markdown 的 Python 工具。它的用途很直接：先把文档变成纯文本结构，再交给模型或编码代理处理，而不是让模型去“看”一个二进制文件。

适合已经要用代理读合同、幻灯片或技术文档的人。先在一小份你有权处理的文件上试转换结果，再接入工作流。转换后的文本仍受原文件版权约束，不要把别人的文档转完再公开发表。

推荐来源：

- [@0x_rody](https://x.com/0x_rody/status/2121328656094244982) 在 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](https://github.com/microsoft/markitdown) 和官方 MCP 包说明 [packages/markitdown-mcp/README.md](https://github.com/microsoft/markitdown/blob/main/packages/markitdown-mcp/README.md)。

**命令行和 Python**

推荐先安装带全部可选依赖的版本：

```bash
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 转写等。

命令行基本用法：

```bash
markitdown path-to-file.pdf -o document.md
```

也可以把文件通过管道交给它：`cat path-to-file.pdf | markitdown`。在 Python 里：

```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**

```bash
pip install markitdown-mcp
markitdown-mcp
```

默认是 STDIO。若改用 Streamable HTTP 和 SSE，官方命令是：

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

官方强调：这个 MCP 包是给本机、受信任的代理用的。HTTP / SSE 默认绑定 `localhost`。不要在未理解安全后果的情况下绑定到其他网卡。服务器没有认证，并以启动它的用户权限运行；`convert_to_markdown` 可以读取该用户能访问的文件或网络数据。

对 Claude Desktop，官方建议用 Docker 镜像，并给出如下配置：

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

若要转换本机文件，需要按 MCP README 把目录挂进容器，例如挂到 `/workdir`。仓库根 README 没有给出 Cursor 或 Claude Code 的现成命令；其他 MCP 客户端若支持标准 stdio 启动方式，可以使用 `markitdown-mcp` 命令，但本文不编造未经官方写出的客户端片段。

## 一个实际例子

下面的步骤是为本文写的核验流程，不是官方固定口令。本次没有实跑，因此不编造转换后的 Markdown。

1. 准备一份你有权处理的短 PDF，放在当前目录，例如 `sample.pdf`。
2. 在已激活的虚拟环境中执行：

```bash
markitdown sample.pdf -o sample.md
```

3. 打开 `sample.md`，检查标题、列表和表格是否还在，有没有明显切断的句子。官方说明它不是为高精度人工排版而设计的；[issue #2370](https://github.com/microsoft/markitdown/issues/2370)（2026-11-15 仍为 open）就报告过 PDF 段落被打断的情况。
4. 若通过 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](https://github.com/microsoft/markitdown) 及其 MCP 包使用 MIT 许可。本文依据 2026-11-15 查阅的根目录 README 和 [markitdown-mcp README](https://github.com/microsoft/markitdown/blob/main/packages/markitdown-mcp/README.md)，用自己的话写成，供 CQBase 上下文库使用。若安装命令、Python 版本或 MCP 绑定方式有变，以这些官方材料为准。

## 收录信息

- 作者: microsoft
- 许可证: MIT
- 来源: https://github.com/microsoft/markitdown
- 收录: 2026-11-15
- GitHub 星标: 195452（采集 2026-11-15）

