pdf-mcp

pdf-mcp

将 PDF 和 Word 文档中的表格转换为 Excel、CSV 或 JSON。 使用简单的浏览器应用，无需配置 Agent；也可以通过 MCP 将相同的确定性提取工具连接到 AI Agent。

浏览器应用用于直接转换表格。它会预览提取的行、突出显示基本结构警告，并将文件保留在你的电脑上。高级配置文件检查还可以验证命名字段、保留来源证据，并针对重复的文档工作流返回 accepted、needs_review 或 rejected。单元格值来自文档解析器，而非生成的模型输出。

需要针对真实文档的配置文件和实测基线？请参阅 Document Reliability Pilot。 Agent 可以使用结构化方案： offers/document-to-excel-pilot.json。

网站：简单转换、本地工具和免费的托管 Agent 测试版。

当前限制： PDF 提取支持原生数字文档。扫描版或仅含图像的 PDF 需要 OCR，本工具未包含该功能。accepted 表示已通过配置的检查；它并不能证明源文档本身正确。

简单的浏览器应用

这是使用 pdf-mcp 最简单的方式。下载应用后，无需 Python、终端、MCP 客户端或 Agent 配置。

1. 打开 v0.4.0 发布页面。
2. 下载适用于 64 位 Windows、Apple silicon Mac 或 64 位 Linux 的 pdf-mcp-app ZIP 文件。
3. 解压并打开 pdf-mcp-app。
4. 浏览器会自动打开。拖入 PDF 或 Word 文档，选择 Excel、CSV 或 JSON，然后点击 转换文档。

完成后，在浏览器中点击 停止应用。该应用仅在你的电脑上运行。转换完成后会立即删除临时文档副本，生成的下载文件会在 30 分钟后或应用停止时过期。目前社区测试版的下载文件尚未签名，因此操作系统可能会询问你是否确定要打开它们。

如果已安装 Python，可以通过以下方式启动相同的界面：

python -m pip install "pdf-agent-mcp @ https://github.com/wesseltl/pdf-mcp/releases/download/v0.4.0/pdf_agent_mcp-0.4.0-py3-none-any.whl"
pdf-mcp-app

简单应用执行的是原始表格提取。“未检测到基本结构问题”不代表准确性有保证。使用提取结果前，请检查重要数值；如果要用于重复的业务工作流，请使用经过配置文件检查的试点方案。

面向 Agent：本地版或免费托管测试版

常规的 pdf-agent-mcp 命令仍在本地运行，采用 MIT 许可，不联网，也不收集遥测数据。 对于明确希望参与受控 Agent 测试版的用户，pdf-agent-cloud-mcp 每次经过身份验证的操作只会上传所选文档。

配置文件检查和评估目前在本地版中运行，或作为付费试点的一部分提供。免费托管测试版目前仅支持原始文本、表格和 CSV 提取。

版本	文档位置	测量方式	适用场景
本地版 pdf-agent-mcp	保留在你的设备上	无	机密文档或不受限制的本地使用
托管版 pdf-agent-cloud-mcp	临时身份验证上传	有限的运行计数器	已脱敏／非敏感数据的测试版评估

免费托管测试版每个自然月包含 25 次操作。每次请求完成后都会删除临时上传的文件。使用指标不包含文件名、文档内容、提取的文本和表格单元格。端点部署完成后即可开放申请。申请时请勿附加文档；只有在端点通过验证后才会开始发送邀请：

申请免费 Agent 测试版访问权限

获批后，请安装并配置独立的桥接程序，使用你收到的端点和密钥：

python -m pip install "pdf-agent-mcp[cloud] @ https://github.com/wesseltl/pdf-mcp/releases/download/v0.4.0/pdf_agent_mcp-0.4.0-py3-none-any.whl"

{
  "mcpServers": {
    "pdf-cloud": {
      "command": "pdf-agent-cloud-mcp",
      "env": {
        "PDF_MCP_CLOUD_URL": "https://endpoint-provided-with-beta-access.example",
        "PDF_MCP_CLOUD_API_KEY": "key-provided-once"
      }
    }
  }
}

仅使用已脱敏或非敏感文件。请参阅免费测试版条款、 隐私声明和机器可读文件 beta/free-hosted-beta.json。

它能将文档转换成什么

这样的 PDF 或 Word 表格：

Item     Qty   Price
Widget    3    12.50
Gadget    1    40.00
Bolt     10     0.25

可以使用 invoice-lines-v1 进行检查，并以规范记录的形式返回，同时给出明确的判定：

{
  "decision": "accepted",
  "profile": {"id": "invoice-lines-v1", "version": "1.0.0"},
  "records": [
    {
      "values": {"item": "Widget", "quantity": "3", "unit_price": "12.50"},
      "evidence": {
        "item": {"page": 1, "table_index": 0, "row": 1, "column": 0, "bbox": [242.9, 136.0, 287.7, 154.0]}
      }
    }
  ]
}

它为 Agent 提供的工具

工具	功能
list_extraction_profiles()	内置配置文件的 ID、版本、字段和哈希值
extract_with_profile(path, profile)	规范记录、单元格依据、校验问题和失败时关闭的判定
export_with_profile(input_path, profile, output_path)	通过配置文件检查的 .xlsx、.csv 或 .json；XLSX 包含 Review、Data 和 Evidence 工作表
page_count(path)	PDF 的页数
extract_text(path, page)	每页文本（单页或整份文档）
extract_tables(path, page, merge_multipage)	原始行、来源坐标和基本解析器警告
table_to_csv(path, page, index)	将一个表格转换为整洁的 CSV 文本
extract_docx_text(path)	.docx 文件中的段落文本
extract_docx_tables(path)	将 Word 表格提取为单元格行，并提供相同的评估字段和合并单元格警告
docx_table_to_csv(path, index)	将一个 Word 表格转换为整洁的 CSV 文本
export_document_tables(input_path, output_path, merge_multipage)	将 PDF/DOCX 表格导出为 .xlsx、.csv 或 .json

Claude Desktop 的 MCP 设置

使用它最快的方式是通过 Claude Desktop 这类 MCP 客户端。只需三步：

1. 安装

python -m pip install "pdf-agent-mcp[mcp] @ https://github.com/wesseltl/pdf-mcp/releases/download/v0.4.0/pdf_agent_mcp-0.4.0-py3-none-any.whl"

2. 将它添加到客户端配置中

Claude Desktop 的配置文件位于：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

添加服务：

{
  "mcpServers": {
    "pdf": { "command": "pdf-agent-mcp" }
  }
}

**3. 重启 Claude Desktop。**你会看到工具图标出现，这表示服务已连接。

完成。现在可以询问设备上任意 .pdf 或 .docx 文件的相关问题：

You:  Check /Users/me/invoices/2024-001.pdf with invoice-lines-v1.

Agent (calls extract_with_profile):
  decision: accepted
  records: 3
  issues: 0

Agent 必须将 needs_review 和 rejected 结果转交给人工处理，不得将其视为可信的业务数据。

**限制文件访问权限：**若要阻止 Agent 读取某个文件夹以外的内容，请设置 PDF_MCP_ALLOWED_DIR。请参阅 SECURITY.md。

与其他 MCP 客户端搭配使用

同一 MCP 服务可用于任何 MCP 客户端，区别仅在于配置。将 pdf-agent-mcp 用作命令。

Cursor — ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（按项目）。结构与 Claude Desktop 相同，并支持热重载（无需重启）：

{ "mcpServers": { "pdf": { "command": "pdf-agent-mcp" } } }

VS Code / GitHub Copilot — .vscode/mcp.json。注意键名不同（servers，而非 mcpServers）， 并且必须设置 type。工具只能在 Copilot Agent 模式下运行：

{ "servers": { "pdf": { "type": "stdio", "command": "pdf-agent-mcp" } } }

Windsurf — ~/.codeium/windsurf/mcp_config.json（如果文件不存在，请创建）。结构与 Claude Desktop 相同：

{ "mcpServers": { "pdf": { "command": "pdf-agent-mcp" } } }

Cline — 在 VS Code 的扩展 MCP 设置面板中添加（命令：pdf-agent-mcp）。

按配置文件检查提取结果

该软件包包含 lab-coa-v1 和 invoice-lines-v1 两个参考配置文件：

extract-document-with-profile examples/invoice.pdf invoice-lines-v1 result.xlsx

退出状态码分别为：accepted 对应 0，needs_review 对应 2，rejected 对应 3。XLSX 输出包含 Review、Data 和 Evidence 工作表。导出到电子表格时，类似公式的文档值会经过转义，而不会执行。

配置文件是普通的带版本 JSON 契约。请参阅 配置文件格式和 机器可读架构。 结果遵循带版本的 提取结果架构。

衡量配置文件效果

根据本地且经客户批准的预期行，衡量字段和记录的精确度：

evaluate-document-profile evaluations/sample-invoice.json

报告包含文档哈希和汇总指标，不包含文档或预期单元格的值。随附示例为合成数据；在宣称对真实文档类别的准确度之前，请构建一组有代表性的私有数据。请参阅 评估指南。

如需更大规模的演示，仓库包含一个 由 18 份文档构成的虚构工作流模拟。 该模拟涵盖 PDF 和 DOCX 变体中的接受、复核和拒绝结果。它是由产品开发者编写的回归测试覆盖，不代表客户验证，也不能证明市场需求。

原始导出

如需直接将文档转换为文件的工作流，请使用 CLI：

export-document-tables report.pdf report.xlsx
export-document-tables coa.docx coa.xlsx
export-document-tables coa.docx coa.json

原始 Excel 导出包含一个 Review 工作表，其中列出表格位置和解析器警告。如果工作流需要规范字段和接受判定，请使用基于配置文件的导出。

了解输出

extract_tables 返回原始行和轻量级解析器诊断信息：

{
  "page": 1,
  "rows": [ ... ],
  "n_rows": 4,
  "looks_clean": true,
  "column_count": 3,
  "empty_ratio": 0.0,
  "warnings": []
}

• looks_clean — true 仅表示这些基本诊断未发现明显问题。它不是准确度评分，也不是接受判定。
• column_count — 如果每行的列数一致，则为列数（如果各行不一致，则为 null）。
• empty_ratio — 空白单元格所占比例。该值较高通常意味着提取结果不佳。
• has_merged_cells — 仅适用于 Word，表示表格中存在合并单元格。Word 会将这些单元格显示为重复值，因此会标记该表格以供复核。
• warnings — 使用简单语言描述的标记，例如 “行列不齐：行包含 [2, 3, 4] 列（网格可能检测错误）” 或 “66% 的单元格为空”。PDF 表格确实难以处理（嵌套/合并单元格、多页），因此该工具不会掩饰问题，而会在结果可疑时告知你。

也可通过纯 Python 使用

from pdf_mcp import docx_extractor, exporter, extractor, verified

result = verified.extract_with_profile("invoice.pdf", "invoice-lines-v1")
if result["decision"] == "accepted":
    rows = [record["values"] for record in result["records"]]

verified.export_with_profile("coa.pdf", "lab-coa-v1", "coa.xlsx")

extractor.extract_tables("invoice.pdf")      # {'tables': [{'rows': [...], 'looks_clean': True, ...}]}
extractor.table_to_csv("invoice.pdf")        # clean CSV of the first table
extractor.extract_text("report.pdf", page=1)

docx_extractor.extract_docx_tables("coa.docx")
docx_extractor.docx_table_to_csv("coa.docx")

exporter.export_document_tables("coa.docx", "coa.xlsx")

测试

python -m pip install -e ".[test]"
python -m unittest discover -s tests     # builds synthetic PDFs, runs anywhere
evaluate-document-profile evaluations/sample-invoice.json
evaluate-document-profile evaluations/simulated-customer/development.json
evaluate-document-profile evaluations/simulated-customer/holdout.json

许可证

MIT