MarkItDown-MCP：微软开源的文档转 Markdown MCP 服务器

本文介绍微软开源的 MarkItDown-MCP 项目，这是一个基于 MCP（Model Context Protocol）协议的服务器，让 AI 助手能够轻松将各种文件和 Office 文档转换为 Markdown 格式。

项目简介

MarkItDown-MCP 是微软 MarkItDown 项目的 MCP 服务器实现，由 AutoGen 团队开发维护。该项目在 GitHub 上已获得超过 8.7 万 stars，是一个广受欢迎的开源工具。

MarkItDown 本身是一个 Python 工具，用于将各种文件格式（PDF、Word、Excel、PowerPoint、图片等）转换为 Markdown 格式。而 MarkItDown-MCP 则将其封装为 MCP 服务器，使 Claude、ChatGPT 等支持 MCP 协议的 AI 助手能够直接调用其文档转换能力。

核心特性

• 多协议支持：支持 STDIO、Streamable HTTP 和 SSE 三种 MCP 传输协议
• 多格式转换：支持 PDF、Word、Excel、PowerPoint、图片、HTML 等多种格式
• URI 兼容：支持 http:、https:、file:、data: 等多种 URI 格式
• Docker 支持：提供官方 Docker 镜像，便于部署和集成
• Claude Desktop 集成：可直接配置到 Claude Desktop 中使用

技术栈

• Python：核心开发语言
• MCP 协议：Model Context Protocol 标准实现
• Docker：容器化部署支持
• FastAPI：HTTP 和 SSE 传输层（基于 Starlette）

安装指南

使用 pip 安装

pip install markitdown-mcp

使用 Docker 运行

构建镜像：

docker build -t markitdown-mcp:latest .

运行容器：

docker run -it --rm markitdown-mcp:latest

如需访问本地文件，需要挂载目录：

docker run -it --rm -v /home/user/data:/workdir markitdown-mcp:latest

挂载后，本地 /home/user/data 目录下的文件将在容器内以 /workdir 路径访问。

快速开始

STDIO 模式（默认）

markitdown-mcp

Streamable HTTP 和 SSE 模式

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

使用示例

在 Claude Desktop 中配置

编辑 claude_desktop_config.json 文件：

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

如需挂载本地目录：

{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/home/user/data:/workdir",
        "markitdown-mcp:latest"
      ]
    }
  }
}

工具调用

MarkItDown-MCP 暴露一个核心工具：convert_to_markdown(uri)

其中 uri 可以是：

• http://example.com/document.pdf - 远程文件
• https://example.com/page.html - 网页
• file:///workdir/document.docx - 本地文件
• data:text/plain;base64,SGVsbG8gV29ybGQ= - Data URI

调试方法

使用 MCP Inspector 工具进行调试：

npx @modelcontextprotocol/inspector

访问 http://localhost:5173/ 连接调试器：

STDIO 模式：

• 选择 STDIO 传输类型
• 输入 markitdown-mcp 命令
• 点击 Connect

Streamable HTTP 模式：

• 选择 Streamable HTTP 传输类型
• 输入 http://127.0.0.1:3001/mcp
• 点击 Connect

SSE 模式：

• 选择 SSE 传输类型
• 输入 http://127.0.0.1:3001/sse
• 点击 Connect

连接后，在 Tools 标签页中点击 List Tools，然后选择 convert_to_markdown 运行工具。

安全注意事项

• 服务器不支持身份验证，以运行用户的权限执行
• 在 SSE 或 Streamable HTTP 模式下，建议绑定到 localhost（默认）
• 生产环境部署时请考虑添加反向代理和身份验证层

项目链接

• GitHub 仓库：https://github.com/microsoft/markitdown
• MCP 包目录：https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp
• PyPI 包：https://pypi.org/project/markitdown-mcp/
• AutoGen 项目：https://github.com/microsoft/autogen