Pdf2md

MCP-PDF2MD

English | 中文

MCP-PDF2MD 服务

一款基于 MCP 的高性能 PDF 转 Markdown 服务，由 MinerU API 提供支持，可批量处理本地文件和 URL 链接，并输出结构化内容。

主要功能

• 格式转换：将 PDF 文件转换为结构化的 Markdown 格式。
• 多源支持：处理本地 PDF 文件和 URL 链接。
• 智能处理：自动选择最佳处理方式。
• 批量处理：支持多文件批量转换，高效处理大量 PDF 文件。
• MCP 集成：与 Claude Desktop 等大模型客户端无缝集成。
• 结构保留：保留原始文档结构，包括标题、段落、列表等。
• 智能布局：按易于阅读的顺序输出文本，适用于单栏、多栏和复杂布局。
• 公式转换：自动识别文档中的公式并转换为 LaTeX 格式。
• 表格提取：自动识别文档中的表格并转换为结构化格式。
• 清理优化：移除页眉、页脚、脚注、页码等，确保语义连贯。
• 高质量提取：从 PDF 文档中高质量提取文本、图像和布局信息。

系统要求

• 软件：Python 3.10+

快速开始

1. 克隆仓库并进入目录：

   git clone https://github.com/FutureUnreal/mcp-pdf2md.git
   cd mcp-pdf2md
   

2. 创建虚拟环境并安装依赖：

   Linux/macOS：

   uv venv
   source .venv/bin/activate
   uv pip install -e .
   

   Windows：

   uv venv
   .venv\Scripts\activate
   uv pip install -e .
   

3. 配置环境变量：

   在项目根目录中创建 .env 文件，并设置以下环境变量：

   MINERU_API_BASE=https://mineru.net/api/v4/extract/task
   MINERU_BATCH_API=https://mineru.net/api/v4/extract/task/batch
   MINERU_BATCH_RESULTS_API=https://mineru.net/api/v4/extract-results/batch
   MINERU_API_KEY=your_api_key_here
   

4. 启动服务：

   uv run pdf2md
   

命令行参数

服务端支持以下命令行参数：

Claude Desktop 配置

在 Claude Desktop 中添加以下配置：

Windows：

{
    "mcpServers": {
        "pdf2md": {
            "command": "uv",
            "args": [
                "--directory",
                "C:\\path\\to\\mcp-pdf2md",
                "run",
                "pdf2md",
                "--output-dir",
                "C:\\path\\to\\output"
            ],
            "env": {
                "MINERU_API_KEY": "your_api_key_here"
            }
        }
    }
}

Linux/macOS：

{
    "mcpServers": {
        "pdf2md": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/mcp-pdf2md",
                "run",
                "pdf2md",
                "--output-dir",
                "/path/to/output"
            ],
            "env": {
                "MINERU_API_KEY": "your_api_key_here"
            }
        }
    }
}

API 密钥配置说明： 你可以通过以下两种方式设置 API 密钥：

1. 在项目目录中的 .env 文件里设置（推荐用于开发）
2. 在上方所示的 Claude Desktop 配置中设置（推荐用于日常使用）

如果在两处都设置了 API 密钥，则以 Claude Desktop 配置中的设置为准。

MCP 工具

该服务提供以下 MCP 工具：

• convert_pdf_url：将 PDF URL 转换为 Markdown
• convert_pdf_file：将本地 PDF 文件转换为 Markdown

获取 MinerU API 密钥

本项目依赖 MinerU API 提取 PDF 内容。获取 API 密钥的方法如下：

1. 访问 MinerU 官方网站 并注册账号
2. 登录后，通过此链接申请 API 测试资格
3. 申请获批后，即可访问 API 管理页面
4. 按照提供的说明生成 API 密钥
5. 复制生成的 API 密钥
6. 将此字符串用作 MINERU_API_KEY 的值

请注意，目前 MinerU API 尚处于测试阶段，需要 MinerU 团队批准才能使用。审批可能需要一些时间，请提前安排。

演示

输入 PDF

输出 Markdown

许可证

MIT 许可证——详情请参阅 LICENSE 文件。

致谢

本项目基于 MinerU 提供的 API 构建。