内容
# MarkItDown-MCP 集成指南
> 一个清晰、验证的、分步骤的指南，介绍如何将微软的 **MarkItDown-MCP** 服务器连接到任何符合模型上下文协议（MCP）的 AI 客户端，以便您的代理可以按需将文档转换为干净、 token 高效的 Markdown。
[](LICENSE)
[](https://github.com/microsoft/markitdown)
[](https://modelcontextprotocol.io)
[](#)
---
## 本指南提供的内容
如果您在大型语言模型的基础上构建任何内容，您需要为上下文窗口中放置的所有内容付费。 其中很大一部分是模型永远不需要的标记：`.docx` 的二进制结构，HTML 的标签混乱，PDF 的布局噪音。 **MarkItDown-MCP** 通过在模型读取之前将源文件转换为干净的 Markdown，从而消除这种开销。
本存储库是一个实用、供应商中立的指南。 它解释了架构，指导您在每种主要的 MCP 主机上安装，并提供现成的配置模板。 这里的每个说明都已针对官方的 `markitdown-mcp` 包和上游微软存储库进行了验证。
**本指南适用于：** AI 工程师、数据科学家、平台团队，以及任何构建检索增强生成（RAG）管道、文档问答系统或需要读取混合格式文件的自主代理的人员。
---
## 一个图示的核心思想
MarkItDown-MCP 位于您的杂乱源文件和 AI 主机之间。 它公开了一个工具，`convert_to_markdown(uri)`，任何符合 MCP 的代理都可以 在对话中调用。 输出的 Markdown 然后准备好进行分块、嵌入、向量存储和检索 — 一种统一的格式，而不管数据最初来自哪里。
---
## 目录
| 文档 | 内容 |
| --- | --- |
| **[docs/01-overview.md](docs/01-overview.md)** | MarkItDown 和 MCP 是什么，以及它们配对的重要性 |
| **[docs/02-architecture.md](docs/02-architecture.md)** | 参考架构、序列流和向量管道上下文 |
| **[docs/03-prerequisites.md](docs/03-prerequisites.md)** | 开始前需要安装的内容 |
| **[docs/04-installation.md](docs/04-installation.md)** | 每个传输和运行时的逐步安装 |
| **[docs/05-client-integration.md](docs/05-client-integration.md)** | 连接 Claude Desktop、Claude Code、Cursor、VS Code 和通用 MCP 主机 |
| **[docs/06-validation-and-testing.md](docs/06-validation-and-testing.md)** | 如何使用 MCP Inspector 证明集成有效 |
| **[docs/07-security.md](docs/07-security.md)** | 信任边界、强化和服务器将执行和不执行的内容 |
| **[docs/08-troubleshooting.md](docs/08-troubleshooting.md)** | 您将遇到的故障模式及其解决方法 |
| **[docs/09-rag-pipeline-integration.md](docs/09-rag-pipeline-integration.md)** | 将 Markdown 输出连接到向量数据库和 RAG 工作流 |
| **[docs/10-faq.md](docs/10-faq.md)** | 常见问题，简洁回答 |
配置模板位于 [`config-templates/`](config-templates/) 下。 示例位于 [`examples/`](examples/) 下。
---
## 五分钟快速入门
最快的路径使用 `uvx`，它在第一次运行时获取并缓存包，无需手动管理虚拟环境。 这在 Linux、macOS 和 Windows 上都有效。
**步骤 1 — 安装 `uv`（提供 `uvx`）。**
```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
**步骤 2 — 确认服务器运行。** 此命令以 STDIO 模式启动服务器，并默默地等待客户端；这种沉默就是成功。 按 `Ctrl+C` 退出。
```bash
uvx markitdown-mcp
```
**步骤 3 — 在 MCP 主机上注册服务器。** 规范条目在大多数主机上都是相同的：
```json
{
"mcpServers": {
"markitdown": {
"command": "uvx",
"args": ["markitdown-mcp"]
}
}
}
```
**步骤 4 — 重启主机并要求其转换文件。**
```
将 file:///绝对路径/to/report.pdf 转换为 markdown 并总结关键点。
```
这就是整个循环。 有关每个客户端的详细信息、传输选择和容器部署，请继续参阅 **[docs/04-installation.md](docs/04-installation.md)**。
---
## 服务器实际执行的操作
`markitdown-mcp` 是 MarkItDown 库周围的一个薄 MCP 包装器。 它公开了一个工具，并支持三种传输。
| 属性 | 详情 |
| --- | --- |
| **工具** | `convert_to_markdown(uri)` — 唯一公开的工具 |
| **接受的 URI 方案** | `http:`、`https:`、`file:`、`data:` |
| **传输** | STDIO（默认）、可流式 HTTP、服务器发送事件（SSE） |
| **依赖** | 固定 `markitdown[all]`，因此每个转换器都随附 |
| **Python** | 3.10 或更高 |
| **许可证** | MIT |
| **转换** | 在内存中执行；不会写入临时文件 |
支持的源格式包括 PDF、Word（`.docx`）、PowerPoint（`.pptx`）、Excel（`.xlsx`、`.xls`）、图像（带有 EXIF 和 OCR）、音频（带有转录）、HTML、CSV、JSON、XML、EPUB、Outlook `.msg`、ZIP 存档（递归处理）和 YouTube 网址。
> **范围说明。** MCP 工具故意公开一个 URI 参数。 库的高级功能 — 大型语言模型图像字幕、Azure 文档智能和第三方插件 — 不会跨越 MCP 边界。 如果您需要这些功能，请直接驱动 Python 库。 这种极简主义是一种设计优势：模型永远不会选择错误的工具，并且没有什么可以配置错误的。
---
## 它如何适用于任何 MCP 解决方案
主机是完全可互换的。 相同的服务器，不变，服务于 Claude Desktop、Claude Code、Cursor、VS Code 和任何其他符合 MCP 的代理。 这就是模型上下文协议的全部意义：一个标准接口意味着您可以配置一次的转换器在任何地方都适用。
---
## 贡献
欢迎提出问题和拉取请求。 请先阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md)。 本指南记录了一个上游微软项目；如果 MarkItDown 本身存在问题，请在 [microsoft/markitdown](https://github.com/microsoft/markitdown/issues) 上报告。
## 许可证
本文档在 [MIT 许可证](LICENSE) 下发布，与上游项目匹配。 MarkItDown 和 MarkItDown-MCP 是微软公司的商标和产品，在此处按照其 [商标和品牌指南](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general) 使用。
## 参考和进一步阅读
- 微软 MarkItDown 存储库 — https://github.com/microsoft/markitdown
- MarkItDown-MCP 包源 — https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp
- PyPI 上的 MarkItDown-MCP — https://pypi.org/project/markitdown-mcp/
- 模型上下文协议规范 — https://modelcontextprotocol.io
- MCP Inspector 工具 — https://github.com/modelcontextprotocol/inspector
