PDF MCP Flow - AI 驱动的 PDF 处理引擎

中文 | English

🚀 专为 LLM 和 RAG 设计的 MCP 文档处理服务器 | PDF 转 Markdown | 格式转换 | 智能提取

MCP PDF Flow 是一个强大的 Model Context Protocol (MCP) 服务器，旨在弥合 LLM（如 Claude）与本地文档之间的鸿沟。

它不仅是PDF 转 Markdown 的最佳工具，还提供了一套完整的文档处理工作流，支持 RAG（检索增强生成） 场景下的数据清洗和格式化。

✨ 核心优势

• 🤖 LLM 友好：输出清洗后的结构化 Markdown，完美适配 AI 上下文阅读。
• 🔍 智能 RAG 支持：支持语义模糊搜索和元数据提取，快速定位文档关键信息。
• 🔄 全能格式转换：PDF ⇋ Word ⇋ Markdown 无缝互转。

✨ 功能特性

• 📝 智能文本提取：
  • 精准提取 PDF 页面文本。
  • 智能 Markdown 识别：自动识别标题、列表、段落结构，合并跨行文本，输出干净的 Markdown。
• 🖼️ 图片提取：
  • 支持提取页面内的所有图片。
  • 自动保存与引用：默认将图片保存到本地 extracted_images/ 目录，并在 Markdown 中插入图片路径引用，避免大量 Base64 数据占用上下文。
  • Base64 预览：可选直接返回图片 Base64 编码，支持在 MCP 客户端中即时预览（适合少量小图）。
• 📂 批量处理：支持对指定目录下的 PDF 文件进行批量提取，自动生成 Markdown 和图片，并保持目录结构整洁。
• 📊 增强表格提取：
  • 高精度识别：自动处理跨行表头、错位列和复杂排版。
  • 智能清洗：自动移除空行、空表头，过滤伪表格（如文本列表）。
  • 批量导出：支持一键提取目录下所有 PDF 中的表格为 Markdown 文件。
• 🔍 模糊搜索：
  • 智能查找：支持通过文件名关键词（模糊匹配、拼写错误兼容）快速定位 PDF 文件路径。
  • 递归搜索：默认支持多级目录递归查找。
• 🔄 格式转换：
  • Markdown 转 Word：将生成的 Markdown 报告一键转换为格式完美的 Word (.docx) 文档。
  • Word 转 PDF：支持将 Word 文档转换为 PDF 文件。
    • 自动适配：优先使用 Microsoft Word，若未安装则自动回退到 WPS Office。
• ⚙️ 灵活提取：支持提取全部页面、指定页码范围（如 1, 1-5）或按关键词智能搜索。
• ℹ️ 元数据获取：支持获取 PDF 标题、作者、页数及目录结构 (TOC)。

🛠️ 环境要求

• 操作系统：Windows (推荐，用于支持 Word/WPS 转换) / macOS / Linux
• Python：>= 3.10
• Office 软件 (仅 Word 转 PDF 功能需要)：
  • Microsoft Word (最佳兼容性)
  • 或 WPS Office (支持 Windows)

📦 安装与使用

本项目使用 uv 进行包管理。

1. 克隆项目

git clone https://github.com/Dublin1231/PDF_MCP_Flow.git
cd mcp-pdf-flow

2. 安装依赖

uv sync

3. 运行服务

本服务是一个 MCP Server，设计为由 Claude Desktop 等客户端自动启动。 您不需要手动在终端运行启动命令。请继续阅读下方的 Claude Desktop 配置 章节完成设置。一旦配置完成，Claude Desktop 启动时会自动在后台运行此服务。

🔌 Claude Desktop 配置

要将此工具添加到 Claude Desktop，请编辑配置文件：

• Windows: %AppData%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

添加以下内容（请务必将路径修改为您本地的实际路径）：

{
  "mcpServers": {
    "simple-pdf": {
      "command": "uv",
      "args": [
        "--directory",
        "D:/path/to/your/mcp-pdf-flow", // ⚠️ 请务必修改为您本地的实际项目路径
        "run",
        "simple-pdf"
      ],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        // (可选) 指定额外的 PDF 搜索路径。Windows 使用分号 (;)，Mac/Linux 使用冒号 (:) 分隔
        "PDF_SEARCH_PATHS": //"D:\\example;E:\\example"
      }
    }
  }
}

注意：

• Windows 用户路径分隔符请使用 / 或 \\。
• PDF_SEARCH_PATHS 为可选配置，用于指定额外的 PDF 搜索路径，多个路径用 ; (Windows) 或 : (Mac/Linux) 分隔。

💬 如何在对话中使用

你不需要手动填写 JSON 参数！ 只需要在对话中告诉 Claude 你想做什么，它会自动调用工具。

场景示例

1. 读取 PDF

• 指定绝对路径：

  用户: "帮我读取 D:\Documents\report.pdf 的第 1 到 5 页。"

• 读取项目目录下文件：

  用户: "读取当前目录下的 test.pdf。" (注：Claude 会自动查找运行目录下的文件)

2. 转换 Markdown 为 Word

用户: "把刚刚提取的内容保存为 Word 文档，放在 D:\Documents\output.docx。"

Claude: (自动调用 convert_markdown_to_docx 工具)

3. Word 转 PDF

用户: "把 D:\Documents\draft.docx 转换成 PDF。"

Claude: (自动调用 convert_docx_to_pdf 工具)

4. 批量处理 PDF

用户: "批量处理 D:\Docs 目录下的所有 PDF，导出为 Markdown。"

Claude: (自动调用 batch_extract_pdf_content 工具)

5. 批量处理并指定输出目录

用户: "批量处理 D:\Docs 下的 PDF，将 Markdown 存到 D:\Output\MD，图片存到 D:\Output\Images。"

Claude: (调用 batch_extract_pdf_content，参数 custom_output_dir="D:\\Output\\MD", custom_image_output_dir="D:\\Output\\Images")

6. 批量处理并平铺输出（不保留目录结构）

用户: "把 D:\Docs 下所有子文件夹里的 PDF 都提取出来，全部放到 D:\All_MDs 这个文件夹里，不要建子文件夹。"

Claude: (调用 batch_extract_pdf_content，参数 custom_output_dir="D:\\All_MDs", preserve_structure=False, create_folder=False)

7. 模糊查找 PDF

用户: "帮我找一下 D:\Study 下面关于 springboot 的 PDF 文件。"

Claude: (自动调用 search_pdf_files 工具)

8. 获取 PDF 目录结构

用户: "提取 D:\Books\Guide.pdf 的目录大纲。"

Claude: (自动调用 get_pdf_metadata 工具)

9. 批量提取表格

用户: "把 D:\Books 下所有 PDF 的表格提取出来，存到 D:\Tables。"

Claude: (自动调用 batch_extract_tables 工具)

📖 工具列表

💡 小贴士：如何获取“绝对路径”？

• Windows: 按住 Shift 键，右键点击文件，选择“复制文件地址 (Copy as path)”。粘贴时去掉首尾的引号。
  • 示例: C:\Users\Name\Documents\report.pdf
• macOS: 选中文件，按下 Option + Command + C 复制路径。
  • 示例: /Users/name/Documents/report.pdf

1. extract_pdf_content

提取 PDF 内容的核心工具。

参数：

• file_path (必填): PDF 文件的绝对路径。
  • Windows 示例: D:\Documents\paper.pdf
  • macOS 示例: /Users/username/Documents/paper.pdf
• page_range (可选): 页码范围，默认为 "all"。
  • 示例: "1", "1-5", "1,3,5", "all"。
• keyword (可选): 关键词搜索。若提供，将忽略页码范围，仅提取包含关键词的页面。
• format (可选): 输出格式。
  • "text" (默认): 纯文本提取。
  • "markdown": 推荐。智能识别标题和段落，适合 LLM 阅读。
  • "json": 返回结构化 JSON 数据，包含每一页的文本和图片信息，适合程序化处理。
• include_text (可选): 是否提取文本，默认为 true。
• include_images (可选): 是否提取图片，默认为 false。
• use_local_images_only (可选): 图片处理模式，默认为 true。
  • true (默认): 图片保存到本地 extracted_images 目录，Markdown 中使用路径引用。推荐用于大文件或包含大量图片的 PDF，防止 Token 溢出。
  • false: 返回图片的 Base64 数据流，可直接预览，但消耗大量 Token。
• skip_table_detection (可选): 极速模式开关，默认为 false。
  • false (默认): 智能检测并提取表格，转换为 Markdown 表格格式。
  • true: 跳过表格检测。适用于仅需要纯文本内容的场景，速度可提升 3-4 倍（约 400+ 页/秒）。

2. batch_extract_pdf_content

批量处理指定目录下的所有 PDF 文件。

参数：

• directory (必填): 要搜索的根目录绝对路径。
• pattern (可选): 文件匹配模式，默认为 **/*.pdf (支持递归)。
• custom_output_dir (可选): 指定输出根目录。如果不填，默认使用项目根目录。最终输出将在该目录下创建 output 文件夹，并根据模式包含以下子目录：
  • output_standard_with_image: 包含图片，标准模式（含表格）。
  • output_fast_with_image_no_table: 包含图片，极速模式（跳过表格检测）。
  • output_standard_no_image: 标准模式+纯文本 (不含图片，含表格)。
  • output_fast_no_image_and_table: 极速模式+纯文本 (不含图片，不含表格)。
  • output_only_image: 仅提取图片模式 (不生成 Markdown 文件，图片保存在 output/output_only_image/extracted_images 目录)。
• format (可选): 输出格式，支持 markdown (默认), json, text。
• include_text (可选): 是否提取文本，默认为 true。
• include_images (可选): 是否提取图片，默认为 false。
• use_local_images_only (可选): 图片处理模式，默认为 true。
• skip_table_detection (可选): 极速模式开关，默认为 false。
  • false (默认): 智能检测并提取表格，转换为 Markdown 表格格式。
  • true: 跳过表格检测。适用于仅需要纯文本内容的场景，速度可提升 3-4 倍（约 400+ 页/秒）。
• create_folder (可选): 是否创建专属文件夹，默认为 false。
  • true: 为每个 PDF 创建专属的同名文件夹（例如 output/subdir/file/file.md）。
  • false (默认): 不创建专属文件夹（例如 output/subdir/file.md）。
• preserve_structure (可选): 目录结构保持开关，默认为 true。
  • true (默认): 保持源文件的目录层级结构（例如 output/SourceSubDir/file.md）。
  • false: 集中/扁平化模式。忽略源目录结构，将所有结果直接放在输出根目录（例如 output/file.md）。

3. get_pdf_metadata

快速获取 PDF 的元数据和目录结构。

参数：

• file_path (必填): PDF 文件的绝对路径。

4. convert_markdown_to_docx

将 Markdown 内容转换为 Word 文档。

参数：

• markdown_content (必填): 要转换的 Markdown 文本内容。
• output_path (必填): 输出 .docx 文件的绝对路径。
  • 注意: 这里需要填写你希望保存的新文件路径。
  • 示例: D:\Documents\report_output.docx

5. convert_docx_to_pdf

将 Word 文档转换为 PDF 文件。

参数：

• docx_path (必填): 输入的 .docx 文件绝对路径。
• pdf_path (可选): 输出 .pdf 文件的绝对路径。
  • 如果不提供，将在原 docx 文件同目录下生成同名 pdf 文件。

6. search_pdf_files

通过文件名模糊搜索 PDF 文件路径。

参数：

• query (必填): 文件名关键词。支持模糊匹配（如拼写错误）、中文匹配。
• directory (可选): 搜索根目录。默认为当前工作目录。
• limit (可选): 返回的最大结果数量，默认 10。
• threshold (可选): 匹配阈值 (0.0-1.0)，默认 0.45。

7. batch_extract_tables

批量提取目录中所有 PDF 的表格。

默认输出路径：

• output/output_only_table: 仅提取表格模式 (表格保存在 output/output_only_table 目录)。

参数：

• directory (必填): 要搜索的根目录绝对路径。
• output_dir (可选): 指定输出根目录。最终表格 Markdown 文件将保存在该目录下的 output/output_only_table 文件夹中。如果不填，默认为当前目录。
• pattern (可选): 文件匹配模式，默认为 **/*.pdf。

✨ 表格提取增强特性：

• 智能表头合并：自动处理跨行表头和被拆分的列名。
• 错位列修复：智能识别并合并因格式问题错位的标题和内容列。
• 空行/空表头优化：
  • 自动移除无效的空行。
  • 智能识别 KV 结构表格，仅在必要时保留表头，避免对中文 KV 表格生成错误的空表头。
• 伪表格过滤：
  • 自动识别并过滤文本列表（如目录、步骤说明）。
  • 自动过滤被误判为表格的代码块或长文本段落。
• 排版优化：智能处理单元格内的换行符，保持列表结构清晰，同时让普通长文本自然回流。

📂 输出目录结构

运行工具后，图片将按以下结构保存：

extracted_images/
  └── PDF文件名/
      ├── page_1_img_1.jpeg
      ├── page_1_img_2.png
      └── ...

💻 开发

• 核心代码: src/simple_pdf/server.py
• 转换逻辑: src/simple_pdf/convert.py