doc2md (Benguy1000)

doc2md

一个MCP服务器，它将PDF、DOCX和PPTX文件转换为磁盘上干净的Markdown文件，可以用作其他MCP服务器中的资源。

为什么存在

LLM工具链、RAG管道和MCP服务器最适合纯文本和Markdown。但是，组织多年来一直将文档锁定在二进制格式中——PDF、Word文档和PowerPoint幻灯片。 doc2md 通过使一切正常化来弥合差距 .md 文件系统上的文件，因此它们可以立即被引用为MCP资源，摄入向量数据库，或添加到知识库中，而无需任何手动清理。

快速开始

pip/uv

# Install with pip
pip install doc2md

# Or with uv
uvx doc2md

码头工人

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

MCP客户端配置

Claude桌面（本地Python）

添加到您的 claude_desktop_config.json:

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

克劳德桌面（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收到未找到路径的诊断时，它将自动切换到这种方法。

克劳德代码

添加到您的项目 .mcp.json 或全局MCP配置：

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

工作目录： Claude Code启动MCP服务器时，您的项目目录为CWD。使用时 base64_content 没有a output_dir，转换 .md 文件将写入您的项目目录。使用 output_dir 以控制输出落在哪里。

光标

{
  "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作为知识库

# Using batch_convert with all PPTX files in a directory
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. 问克劳德：“将/path/to/quarterly-report.pdf转换为markdown”
3. 这 .md 文件已写入磁盘，可以在后续查询中引用

配置

Docker使用

挂载你的文件目录，这样doc2md就可以读取源文件并写入输出：

# stdio mode (for MCP clients)
docker run -v $(pwd):/data benguy1000/doc2md

# SSE mode (for network access)
docker run -p 3000:3000 -v $(pwd):/data -e TRANSPORT=sse benguy1000/doc2md

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

贡献

1. 克隆仓库
2. 安装开发依赖项： pip install -e ".[dev]"
3. 运行测试： pytest
4. 棉绒： ruff check src/ tests/
5. 格式： ruff format src/ tests/

许可证

麻省理工学院 --版权所有（c）2025 benguy1000