AI导哈

PDF处理服务

一个基于PyPDFium2的PDF处理和分析服务，提供文本提取、元数据提取、搜索、页面操作、表格处理等功能。

  • by gzigurella
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 gzigurella/pdf-mcp

使用说明

PDF MCP

使用PyPDFium2进行PDF处理和分析的MCP服务器。

特性

  • 提取文本：从支持页面范围的PDF文件中提取文本内容
  • 提取元数据：提取PDF元数据，包括标题、作者和页数
  • 搜索文本：在带有上下文的PDF文件中搜索特定文本
  • get_page_count：获取PDF文件中的总页数
  • 提取页面：从PDF中提取特定页面并另存为新的PDF
  • split_pdf：使用base64编码将PDF拆分为多个基于页面的PDF
  • 合并dfs：将多个PDF文件合并为一个PDF
  • pdf_to_images：使用可配置的DPI将PDF页面转换为PNG图像
  • get_form_fields：从PDF中提取所有表单字段，包括名称、类型和值
  • fill_form：用提供的值填充PDF中的表单字段并保存到输出路径

安装

来自Git仓库

# Clone the repository
git clone https://github.com/gzigurella/pdf-mcp.git
cd pdf-mcp

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package
pip install -e .

紫外线（推荐）

# Clone and enter directory
git clone https://github.com/gzigurella/pdf-mcp.git
cd pdf-mcp

# Install with uv
uv pip install -e .

整合

开源代码

添加到您的 ~/.config/opencode/opencode.json:

{
  "mcpServers": {
    "pdf-mcp": {
      "type": "local",
      "command": [
        "/path/to/pdf-mcp/venv/bin/python",
        "-m",
        "pdf_mcp"
      ],
      "enabled": true
    }
  }
}

克劳德桌面

添加到您的Claude Desktop配置中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pdf-mcp": {
      "command": "/path/to/pdf-mcp/venv/bin/python",
      "args": ["-m", "pdf_mcp"]
    }
  }
}

通用MCP客户端

对于任何兼容MCP的客户端：

# Start the server directly
/path/to/venv/bin/python -m pdf_mcp

服务器使用MCP协议通过stdio进行通信。

工具

提取文本

从PDF文件中提取文本内容。支持具有可搜索文本的PDF，并可以从特定页面或范围中提取文本。

参数 类型 必填 默认 说明
file_path string 是 - 从中提取文本的PDF文件的路径
pages string No “all” 要提取的页面范围（例如，“1-5”、“3,7,9”、“all”） 
{
  "file_path": "/path/to/document.pdf",
  "pages": "1-5"
}

提取元数据

从PDF文件中提取元数据，包括标题、作者、主题、关键字、创建者、生产者、创建日期、修改日期和页数。

参数 类型 必填 默认 说明
file_path string 是 - 要从中提取元数据的PDF文件的路径 
{
  "file_path": "/path/to/document.pdf"
}

搜索文本

在PDF文件中搜索特定文本。返回找到的文本的页码和上下文。可用于在大型文档中查找特定内容。

参数 类型 必填 默认 说明
file_path string 是 - 要搜索的PDF文件的路径
query string Yes - 要在PDF中搜索的文本
case_sensitive boolean 否 false 是否执行区分大小写的搜索
context_words integer 否 10 每次匹配前后要包含的单词数 
{
  "file_path": "/path/to/document.pdf",
  "query": "important term",
  "case_sensitive": false,
  "context_words": 5
}

get_page_count

获取PDF文件中的总页数。返回一个简单的整数计数。

参数 类型 必填 默认 说明
file_path string 是 - 要计算页数的PDF文件的路径 
{
  "file_path": "/path/to/document.pdf"
}

提取页面

从PDF文件中提取特定页面并另存为新的PDF。支持页面范围和单个页面选择。

参数 类型 必填 默认 说明
file_path string 是 - 源PDF文件的路径
pages string Yes - 要提取的页面（例如，'1-5'、'3,7,9'、'1,3-5'）
output_path string 是 - 提取的页面将保存为新PDF的路径 
{
  "file_path": "/path/to/source.pdf",
  "pages": "1,3,5-7",
  "output_path": "/path/to/output.pdf"
}

split_pdf

根据页面范围将PDF文件拆分为多个单独的PDF文件。为每个选定页面返回一个包含base64编码PDF的JSON。支持单页、页面范围和所有页面。

参数 类型 必填 默认 说明
file_path string 是 - 要拆分的PDF文件的路径
page_range string 是 - 要拆分的页面范围-“全部”、单页（例如“1”）或范围（例如“1-3”、“2-5”） 
{
  "file_path": "/path/to/document.pdf",
  "page_range": "1-3"
}

合并dfs

将多个PDF文件合并为一个PDF。文件将按提供的顺序合并。

参数 类型 必填 默认 说明
file_paths array 是 - 要合并的PDF文件路径列表
output_path string 是 - 合并PDF的保存路径 
{
  "file_paths": ["/path/to/doc1.pdf", "/path/to/doc2.pdf", "/path/to/doc3.pdf"],
  "output_path": "/path/to/merged.pdf"
}

pdf_to_images

将PDF页面转换为PNG图像。为每个页面返回一个带有base64编码的PNG图像的JSON。支持自定义DPI设置以控制分辨率。

参数 类型 必填 默认 说明
file_path string 是 - 要转换为图像的PDF文件的路径
dpi 整数 否 150 图像分辨率（每英寸点数）
format string 否 “png” 图像格式（仅png） 
{
  "file_path": "/path/to/document.pdf",
  "dpi": 300,
  "format": "png"
}

get_form_fields

从PDF文档中提取所有表单字段，包括字段名称、类型、当前值和下拉字段的可用选项。

参数 类型 必填 默认 说明
file_path string 是 - 从中提取表单字段的PDF文件的路径 
{
  "file_path": "/path/to/form.pdf"
}

返回一个包含字段信息的JSON：

{
  "fields": [
    {
      "name": "first_name",
      "type": "text",
      "value": "",
      "page": 1,
      "rect": {"x0": 50, "y0": 72, "x1": 150, "y1": 92}
    },
    {
      "name": "country",
      "type": "combobox",
      "value": "",
      "page": 1,
      "rect": {...},
      "choices": ["USA", "Canada", "UK"]
    },
    {
      "name": "accept_terms",
      "type": "checkbox",
      "value": "",
      "page": 1,
      "rect": {...},
      "on_state": "Yes"
    }
  ],
  "total_fields": 3
}

fill_form

用提供的值填充PDF文档中的表单字段并保存到输出路径。支持文本字段、复选框、单选按钮和下拉菜单。

参数 类型 必填 默认 说明
file_path string 是 - 源PDF文件的路径
字段 对象 是 - 字段名称及其值的字典
output_path string 是 - 保存已填写PDF的路径 
{
  "file_path": "/path/to/form.pdf",
  "fields": {
    "first_name": "John",
    "last_name": "Doe",
    "country": "USA",
    "accept_terms": true
  },
  "output_path": "/path/to/filled_form.pdf"
}

复选框值接受： true/false, "yes"/"no", "1"/"0". 单选按钮：使用以下值 on_state 字段（使用 get_form_fields 第一）。

配置

环境变量

变量 默认值 描述
PDF_MCP_DEBUG false 启用调试日志记录 
# Example
export PDF_MCP_DEBUG=true
python -m pdf_mcp

发展

运行测试

source venv/bin/activate
pytest

# With coverage
pytest --cov=src --cov-report=html

项目结构

pdf-mcp/
├── src/pdf_mcp/
│   ├── __init__.py
│   ├── __main__.py
│   ├── server.py
│   ├── config.py
│   └── tools/
│       ├── __init__.py
│       ├── extract_text.py
│       ├── extract_metadata.py
│       ├── search_text.py
│       ├── get_page_count.py
│       ├── extract_pages.py
│       ├── split_pdf.py
│       ├── merge_pdfs.py
│       ├── pdf_to_images.py
│       ├── get_form_fields.py
│       └── fill_form.py
├── tests/
├── pyproject.toml
└── README.md

故障排除

安装问题

如果你遇到安装错误，请确保你有Python 3.10或更高版本：

python --version

找不到文件错误

确保PDF文件路径正确且文件存在：

ls -l /path/to/your/document.pdf

加密PDF

如果尝试处理加密的PDF，这些工具将引发RuntimeError。确保您的PDF没有密码保护。

大型PDF的内存问题

对于非常大的PDF文件，考虑使用 extract_pages 或 split_pdf 工具。

权限错误（Linux）

如果您遇到权限错误，请确保PDF文件可读：

chmod +r /path/to/your/document.pdf

安全注意事项

  • 文件访问：服务器只处理存在且运行进程可读的文件
  • 路径验证：在处理之前，所有文件路径都经过验证
  • 无网络访问：服务器未发出任何网络请求
  • 临时文件：临时文件在处理后被正确清理
  • 错误处理：敏感信息不会在错误消息中暴露
  • 加密PDF：受密码保护的PDF将被拒绝，并显示相应的错误消息

示例使用场景

场景1：从特定页面提取文本

{
  "name": "extract_text",
  "arguments": {
    "file_path": "/documents/report.pdf",
    "pages": "1-3,7,9"
  }
}

场景2：搜索和提取上下文

{
  "name": "search_text",
  "arguments": {
    "file_path": "/documents/contract.pdf",
    "query": "liability clause",
    "case_sensitive": true,
    "context_words": 15
  }
}

场景3：合并多个报告

{
  "name": "merge_pdfs",
  "arguments": {
    "file_paths": [
      "/reports/q1.pdf",
      "/reports/q2.pdf", 
      "/reports/q3.pdf",
      "/reports/q4.pdf"
    ],
    "output_path": "/reports/annual.pdf"
  }
}

场景4：将PDF转换为图像

{
  "name": "pdf_to_images",
  "arguments": {
    "file_path": "/documents/presentation.pdf",
    "dpi": 300
  }
}

许可证

麻省理工学院

相关 MCP