Doc2md

🚀 doc2md

doc2md 是一个 MCP 服务器，它可以将 PDF、DOCX 和 PPTX 文件转换为干净的 Markdown 文件并保存到磁盘，这些文件可直接作为其他 MCP 服务器的资源使用。

🚀 快速开始

使用 pip 或 uv 安装

# 使用 pip 安装
pip install doc2md

# 或者使用 uv 安装
uvx doc2md

使用 Docker 安装

docker run -v $(pwd):/data benguy1000/doc2md

✨ 主要特性

LLM 工具链、RAG 管道和 MCP 服务器在处理纯文本和 Markdown 时表现最佳。但许多组织有大量以二进制格式（如 PDF、Word 文档和 PowerPoint 演示文稿）存储的文档。doc2md 可以将这些文件统一转换为文件系统上的 .md 文件，从而可以立即将它们作为 MCP 资源引用、导入向量数据库或添加到知识库中，无需任何手动清理。

📦 安装指南

pip / uv

# 使用 pip 安装
pip install doc2md

# 或者使用 uv 安装
uvx doc2md

Docker

docker run -v $(pwd):/data benguy1000/doc2md

💻 使用示例

基础用法

MCP 客户端配置

Claude Desktop（本地 Python）

在 claude_desktop_config.json 中添加以下内容：

{
  "mcpServers": {
    "doc2md": {
      "command": "python",
      "args": ["-m", "doc2md"],
      "env": {
        "TRANSPORT": "stdio"
      }
    }
  }
}

Claude Desktop（Docker）

如果使用基于 Docker 的 MCP 服务器运行 Claude Desktop，请挂载文件目录，以便容器可以访问它们：

{
  "mcpServers": {
    "doc2md": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/path/to/your/files:/data",
        "benguy1000/doc2md"
      ]
    }
  }
}

⚠️ 重要提示

在沙盒或 Docker 环境中，主机文件路径（例如 /mnt/user-data/uploads/）可能在容器内无法访问。如果文件路径无法解析，请使用 base64_content 和 file_name 参数 —— 当 LLM 收到路径未找到的诊断信息时，会自动切换到这种方法。

Claude Code

在项目的 .mcp.json 或全局 MCP 配置中添加以下内容：

{
  "mcpServers": {
    "doc2md": {
      "command": "python",
      "args": ["-m", "doc2md"]
    }
  }
}

💡 使用建议

Claude Code 以项目目录作为当前工作目录启动 MCP 服务器。当使用 base64_content 且未指定 output_dir 时，转换后的 .md 文件将写入项目目录。可以使用 output_dir 来控制输出位置。

Cursor

{
  "mcpServers": {
    "doc2md": {
      "command": "python",
      "args": ["-m", "doc2md"],
      "transport": "stdio"
    }
  }
}

通用 MCP 客户端（Docker + SSE）

{
  "mcpServers": {
    "doc2md": {
      "url": "http://localhost:3000/sse",
      "transport": "sse"
    }
  }
}

高级用法

工具使用示例

convert_pdf_to_markdown

将 PDF 文件转换为结构化的 Markdown 文件，保留标题、段落、列表、表格和分页符。 输入：

{
  "file_path": "/path/to/report.pdf",
  "output_dir": "/path/to/output",
  "overwrite": false
}

输出：

{
  "success": true,
  "output_path": "/path/to/output/report.md",
  "file_name": "report.md",
  "source_file": "report.pdf",
  "metadata": {
    "source_format": "pdf",
    "page_count": 12,
    "word_count": 4500,
    "has_images": true,
    "image_count": 3,
    "conversion_warnings": []
  }
}

convert_docx_to_markdown

将 DOCX 文件转换为 Markdown 文件，保留标题、格式（粗体、斜体、删除线）、表格、列表、超链接、脚注和注释。 输入：

{
  "file_path": "/path/to/document.docx",
  "output_dir": "/path/to/output"
}

输出：

{
  "success": true,
  "output_path": "/path/to/output/document.md",
  "file_name": "document.md",
  "source_file": "document.docx",
  "metadata": {
    "source_format": "docx",
    "page_count": 1,
    "word_count": 2300,
    "has_images": false,
    "image_count": 0,
    "conversion_warnings": []
  }
}

convert_pptx_to_markdown

将 PPTX 文件转换为 Markdown 文件，每个幻灯片成为一个带有标题、正文文本、表格和演讲者备注的 H2 部分。 输入：

{
  "file_path": "/path/to/deck.pptx",
  "output_dir": "/path/to/output"
}

输出：

{
  "success": true,
  "output_path": "/path/to/output/deck.md",
  "file_name": "deck.md",
  "source_file": "deck.pptx",
  "metadata": {
    "source_format": "pptx",
    "slide_count": 20,
    "word_count": 1800,
    "has_images": true,
    "image_count": 5,
    "conversion_warnings": []
  }
}

convert_auto

根据文件扩展名或 MIME 类型自动检测文件类型，并路由到正确的转换器。 输入：

{
  "file_path": "/path/to/any-document.pdf",
  "output_dir": "/path/to/output"
}

batch_convert

一次转换多个文件，个别文件转换失败时会继续处理其他文件。 输入：

{
  "file_paths": [
    "/path/to/report.pdf",
    "/path/to/notes.docx",
    "/path/to/slides.pptx"
  ],
  "output_dir": "/path/to/output"
}

输出：

{
  "results": [
    { "success": true, "output_path": "/path/to/output/report.md", "..." : "..." },
    { "success": true, "output_path": "/path/to/output/notes.md", "..." : "..." },
    { "success": true, "output_path": "/path/to/output/slides.md", "..." : "..." }
  ],
  "total": 3,
  "successful": 3,
  "failed": 0
}

Base64 输入（所有单文件工具）

所有单文件工具也接受 base64 编码的内容，而不是文件路径：

{
  "base64_content": "JVBERi0xLjQK...",
  "file_name": "report.pdf",
  "output_dir": "/path/to/output"
}

常见工作流程示例

将销售演示文稿文件夹转换为 Markdown 并用于知识库

# 使用 batch_convert 处理目录中的所有 PPTX 文件
python -c "
from doc2md.tools.batch import batch_convert
from pathlib import Path

files = [str(f) for f in Path('/data/sales-decks').glob('*.pptx')]
result = batch_convert(files, output_dir='/data/knowledge-base')
print(f'Converted {result.successful}/{result.total} files')
"

将转换后的文档导入向量数据库

1. 使用 doc2md 将所有文档转换为 .md 文件。
2. 将 RAG 管道的文档加载器指向输出目录。
3. 具有一致标题层次结构的干净 Markdown 文件使分块更加可靠。

与 Claude Desktop 一起使用以转换并查询文档

1. 在 Claude Desktop 中将 doc2md 配置为 MCP 服务器。
2. 向 Claude 询问：“将 /path/to/quarterly-report.pdf 转换为 Markdown”。
3. .md 文件将写入磁盘，并可在后续查询中引用。

📚 详细文档

配置

Docker 使用方法

挂载文件目录，以便 doc2md 可以读取源文件并写入输出：

# stdio 模式（用于 MCP 客户端）
docker run -v $(pwd):/data benguy1000/doc2md

# SSE 模式（用于网络访问）
docker run -p 3000:3000 -v $(pwd):/data -e TRANSPORT=sse benguy1000/doc2md

输出的 .md 文件将出现在主机文件系统的挂载目录中。

🔧 技术细节

本项目的开发和使用涉及到 Python 环境，使用 pip 或 uv 进行安装，也支持 Docker 部署。在 MCP 客户端配置方面，针对不同的客户端（如 Claude Desktop、Claude Code、Cursor 等）提供了相应的配置示例。工具方面，提供了多种文件转换工具，包括 convert_pdf_to_markdown、convert_docx_to_markdown 等，并且支持批量转换和 Base64 输入。

📄 许可证

MIT — 版权所有 (c) 2025 benguy1000