Intelligent Document Extraction - ComIDP

English | 繁體中文 | 日本語 | 简体中文

ComPDF MCP

ComPDF MCP 专为 MCP 客户端和 AI Agent 平台打造，提供 PDF/图像解析与数据提取、PDF 转换、PDF 编辑和图像转换功能。它可以帮助用户先处理原始文档，再将更轻量、更整洁、结构更清晰的结果交给 AI，从而减少 Token 用量、降低 AI 成本，并提升整体处理效率。

• 如果您觉得 ComPDF MCP 实用，欢迎在 GitHub 上为我们点亮 ⭐ Star。这有助于我们不断发展和改进。
• 有问题或想法？欢迎加入我们的 讨论区。

为什么选择 ComPDF MCP • 功能 • 技术架构 • 快速开始 • 部署与运维 • 许可证与免费访问 • 使用场景与提示词示例 • 支持

为什么选择 ComPDF MCP

用户选择 ComPDF MCP 的核心原因，并不只是让 AI 处理 PDF，而是在交给 AI 进行分析、总结、问答或自动化处理之前，先将复杂、冗长且信息杂乱的源文档转换为更便于模型理解的输入。

原始 PDF、扫描文件和图像文件通常体积更大、信息更杂乱，结构也不够稳定。使用 ComPDF MCP 先进行转换、提取和页面级处理，再将结果交给 AI，用户可以：

• 减少 AI Token 用量
• 降低 AI 成本
• 缩短响应时间
• 提升结构化输出的质量
• 避免将模型预算浪费在杂乱的原始文件上
• 通过一个 MCP 服务处理 PDF 和图像
• 适用于以文档为主的工作流和多平台 Agent 场景

批量处理报告、合同、发票、表格、扫描文件和类似文档时，这种方法尤其有价值。在这些情况下，“先处理文档，再调用 AI”的工作流通常更具成本效益，也比直接将原始文件发送给模型更适合后续自动化处理。

功能

ComPDF MCP 专注于三大能力：文档转换、PDF 操作，以及智能解析与数据提取。

1. PDF 和图像转换

功能	描述
PDF 转 Word	将 PDF 文件转换为可编辑的 Word 文档，并尽可能保留原始布局、文本、图像和格式。
PDF 转 Excel	将 PDF 文件转换为 Excel 工作簿，支持表格、数字和结构化业务数据。
PDF 转幻灯片	将 PDF 页面转换为可编辑的 PowerPoint 幻灯片，并尽可能保留原始布局和视觉结构。
PDF 转 HTML	将 PDF 文件转换为 HTML，用于网页展示和内容复用，同时保留文本、图像、表格和布局。
PDF 转 RTF	将 PDF 文件转换为 RTF 文档，支持文本和图像内容。
PDF 转图像	将 PDF 页面转换为 PNG 或 JPG 图像，并可配置分辨率和 DPI。
PDF 转 CSV	从 PDF 文件中提取表格并导出为 CSV，可逐个导出表格，也可合并输出。
PDF 转 TXT	从 PDF 或扫描版 PDF 文件中提取文本，并将其保存为纯文本。
PDF 转 JSON	从 PDF 文件中提取文本、表格和图像，并将其保存为结构化 JSON。
PDF 转 Markdown	将 PDF 文件转换为 Markdown，方便在知识库、开发者文档、博客系统和 AI 工作流中复用。
PDF 转可搜索 PDF	对扫描版 PDF 进行 OCR，生成可搜索的 PDF，其中的文本可选择、复制和高亮，适用于检索、归档和后续处理。
PDF 转 OFD	将 PDF 文件转换为 OFD 文件，适用于 OFD 归档、文档流转和本地化办公场景。
Word 转 PDF	将 Word 文档转换为 PDF，并尽可能保留布局、字体、图像和页面结构，便于分享、归档和打印。
PNG 转 PDF	将 PNG 图像转换为 PDF，便于打包、分享、打印和归档屏幕截图、设计文件或配套图像素材。
RTF 转 PDF	将 RTF 文档转换为 PDF，同时保留核心文本样式和布局，便于在不同设备上保持一致的查看效果并用于正式输出。
Excel 转 PDF	将 Excel 工作簿或电子表格转换为 PDF，便于分享报告、打印、归档，并防止公式被意外修改。
TXT 转 PDF	将纯 TXT 文件转换为 PDF，便于将日志、笔记和文本说明整理为固定版式的文档。
CSV 转 PDF	将 CSV 表格数据转换为 PDF，便于快照分享、审阅、打印和业务归档。
幻灯片转 PDF	将 PowerPoint 演示文稿转换为 PDF，便于分发演示内容、跨设备查看和正式存档。
HTML 转 PDF	将 HTML 页面或内容片段转换为 PDF，适用于网页保存、报告导出、邮件归档和可打印输出。
图像转 Word	将 JPG、JPEG、PNG 和 BMP 图像文件转换为可编辑的 Word 文档。
图像转 Excel	将图像文件转换为 Excel 工作簿，支持表格、文本和数字内容。
图像转 PPT	将图像文件转换为可编辑的 PowerPoint 幻灯片，并尽可能保留可见布局和内容结构。
图像转 PDF	将 JPG、JPEG、PNG、BMP 及类似图像文件转换为 PDF，便于整合、分享、打印和归档一张或多张图像。
图像转 HTML	将图像文件转换为 HTML，并尽可能保留文本、布局、表格和主要视觉元素。
图像转 RTF	将图像文件转换为 RTF 文档，支持提取文本和图像。
图像转 CSV	从图像文件中提取表格并导出为 CSV。
图像转 TXT	从图像文件中提取文本，并将其保存为纯文本。
图像转 JSON	从图像文件中提取文本、表格和图像，并将其保存为结构化 JSON。

2. PDF 编辑、保护与比较

功能	描述
合并 PDF 文件	将多个 PDF 文件合并为一个 PDF 文档。
拆分 PDF 文件	将一个 PDF 文件拆分为多个较小的 PDF 文件。
旋转 PDF 页面	将选定的 PDF 页面旋转 90、180 或 270 度。
删除 PDF 页面	从 PDF 文件中移除一个或多个页面。
插入 PDF 页面	将另一个 PDF 中的页面插入现有 PDF。
提取 PDF 页面	提取选定页面或页面范围，并将其另存为新文件。
转换 PDF 标准	转换 PDF 的符合性或归档标准。
添加水印	为 PDF 文件添加文本或图像水印，用于品牌宣传或使用控制。
移除水印	从受支持的 PDF 文件中移除文本或图像水印。
压缩 PDF	减小 PDF 文件大小，便于存储、上传和共享。
加密 PDF	使用 AES 加密和权限控制保护 PDF 文件。
解密 PDF	移除已授权 PDF 文件的密码，以便内部处理或重复使用。
比较 PDF	比较两个 PDF 文件之间的内容差异。

3. 智能解析与数据提取

功能	描述
智能文档解析	将 PDF 和图像解析为结构化文档输出，供 Agent、自动化工作流和下游系统使用。
从 PDF 和图像中智能提取数据	从 PDF 和图像中提取文本、表格和内容字段等有价值的业务数据。

技术架构

本项目是使用 Python、FastMCP 和 Starlette 构建的 MCP Streamable HTTP 服务。工具参数架构根据随附的官方 OpenAPI 参数快照生成，服务会拒绝未知参数。

客户端可以通过聚合端点访问所有工具：

http://127.0.0.1:8000/mcp

如果只需要 ComPDF MCP 的部分功能，请使用以下模块端点：

模块	MCP 端点	业务工具数	代表性工具
PDF 和图像转换	/mcp/conversion/mcp	28	pdf_to_word、pdf_to_markdown、image_to_json、word_to_pdf 等
智能解析和数据提取	/mcp/ai/mcp	2	document_parse、document_extract
PDF 编辑、保护和比较	/mcp/pdf/mcp	13	merge_pdf、add_watermark、encrypt_pdf、compare_pdf 等
所有功能	/mcp	44	以上所有工具

所有业务工具都使用统一的文件输入格式。options 中的键必须使用 ComPDF API 文档中的 camelCase 参数名称。只有 htmlFile、templateFile、dataFile、imageFile 和 iccFile 可以通过 special_files 上传。

{
  "files": [
    {
      "filename": "report.pdf",
      "content_base64": "JVBERi0xLjc...",
      "content_type": "application/pdf"
    }
  ],
  "options": {
    "pageRanges": "1-3,6",
    "enableOcr": 1
  },
  "special_files": {
    "imageFile": {
      "filename": "watermark.png",
      "content_base64": "iVBORw0..."
    }
  }
}

单个 Base64 文件解码后的大小上限为 100 MB。同步工具响应包含 ComPDF 结果、相关的官方文档 URL，以及下载 URL 将在 24 小时后过期的说明。

快速开始

1. 安装并运行服务

前提条件：Python 3.10+。在仓库根目录下创建虚拟环境，并以可编辑模式安装软件包。

Windows：

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e .
Copy-Item .env.example .env
compdf-streaming-mcp

Linux / macOS：

python3 -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env
compdf-streaming-mcp

服务默认监听 0.0.0.0:8000。使用以下端点检查其状态：

• GET /healthz：服务状态和已挂载的 MCP 路由。
• GET /readyz：就绪状态，不会调用上游 ComPDF API。
• GET /metrics：Prometheus 文本格式的请求计数器。

2. 配置服务

将 .env.example 复制为 .env，然后根据部署环境调整设置。服务器不会存储或配置用户的 ComPDF API 密钥。每个 MCP 请求都通过 X-ComPDF-API-Key 标头提供该用户的密钥。你可以注册 ComPDF Portal，并从下方所示位置复制免费 API 密钥。

COMPDF_API_BASE_URL=https://api-server.compdf.com/server
COMPDF_API_TIMEOUT_SECONDS=180
MCP_HOST=0.0.0.0
MCP_PORT=8000
MCP_ALLOWED_HOSTS=localhost,localhost:*,127.0.0.1,127.0.0.1:*,mcp.example.com
MCP_RATE_LIMIT_PER_MINUTE=120

中国大陆账号请使用 COMPDF_API_BASE_URL=https://api-server.compdf.cn/server。在生产环境中，将反向代理域名添加到 MCP_ALLOWED_HOSTS；在适当情况下，请包含非默认端口，或使用 mcp.example.com:*。

3. 配置 MCP 客户端

以下示例使用统一的 MCP URL http://127.0.0.1:8000/mcp。如果部署在远程服务器上，请将其替换为公开的 HTTPS 地址，例如 https://your-domain.example/mcp。

首先获取个人 ComPDF API 密钥（注册以获取免费 API 密钥）。对于使用环境变量的客户端，请先在客户端机器上设置密钥：

$env:COMPDF_API_KEY = "your-own-compdf-api-key"

Codex

将远程 MCP 服务添加到 ~/.codex/config.toml：

[mcp_servers.compdf]
url = "http://127.0.0.1:8000/mcp"
env_http_headers = { "X-ComPDF-API-Key" = "COMPDF_API_KEY" }
tool_timeout_sec = 180

Claude（Claude Code）

将以下 MCP 服务添加到用户级配置文件 ~/.claude.json。启动 Claude Code 时所用的终端会话必须能够访问 COMPDF_API_KEY：

{
  "mcpServers": {
    "compdf": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "X-ComPDF-API-Key": "${COMPDF_API_KEY}"
      }
    }
  }
}

如果 ~/.claude.json 中已有配置，请将 compdf 合并到现有的 mcpServers 对象中，而不是覆盖该文件。

GitHub Copilot（VS Code）

在 VS Code 命令面板中运行 MCP: Open User Configuration，或在工作区中创建 .vscode/mcp.json，然后添加以下配置。首次使用时，VS Code 会在密码字段中提示输入 API 密钥：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "compdf-api-key",
      "description": "ComPDF API Key",
      "password": true
    }
  ],
  "servers": {
    "compdf": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "X-ComPDF-API-Key": "${input:compdf-api-key}"
      }
    }
  }
}

Cursor

打开 Cursor Settings > Tools & MCP，选择 New MCP Server，或编辑 ~/.cursor/mcp.json，然后添加：

{
  "mcpServers": {
    "compdf": {
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "X-ComPDF-API-Key": "your-own-compdf-api-key"
      }
    }
  }
}

此 Cursor 配置会将密钥存储在本地配置文件中。不要提交包含密钥的 ~/.cursor/mcp.json 或项目级配置文件。

所有客户端都必须在每个 MCP 请求中发送 X-ComPDF-API-Key。不要将密钥作为工具参数、URL 参数或聊天消息传递。

4. 异步和预签名上传

除了 44 个同步业务工具外，每个模块还提供 list_operations 和以下任务工具：

• start_async_operation：调用匹配的 /v2/processAsync/... 端点，处理耗时较长或涉及多个文件的任务。
• get_task_status：从 /v2/task/taskInfo 查询任务状态。
• create_presigned_upload、upload_presigned_file 和 start_presigned_operation：依次创建预签名任务、上传文件并启动任务。

预签名上传仅支持使用一个标准文件的操作。PDF 合并、比较、插入页面等操作请使用异步模式。预签名 URL 仅保留在创建它的模块服务的内存中，绝不会作为工具参数或响应字段公开。

部署和运维

使用 Docker Compose 构建并运行服务：

docker compose up --build

在生产环境中，应通过 HTTPS 反向代理将聚合端点公开为 https://your-domain.example/mcp，并配置 MCP_ENV=production、MCP_PUBLIC_URL、MCP_OAUTH_ISSUER_URL 和 MCP_STATIC_TOKENS_JSON。启用后，客户端还必须发送 Authorization: Bearer <token>；此服务令牌与每位用户的 ComPDF API 密钥相互独立。有关镜像传输、HTTPS 代理、更新和回滚的说明，请参阅 DEPLOYMENT.md。

许可证和免费使用

ComPDF MCP 可免费使用，无需购买或联系销售人员。

• 注册以获取免费 API 密钥并完成配置

• 适用于个人试用、功能验证和工作流测试

• 如果需要更高的 API 资源、企业部署或商业合作，请联系销售团队

这降低了使用门槛，让您可以更轻松地测试真实的 AI 文档工作流，再决定是否深入用于业务。

使用场景和示例提示词

上传 PDF、图像或其他源文件。输入任务指令，例如提取表格、转换格式、合并 PDF 或添加水印。Agent 会调用相应的 ComPDF Server 工具并返回结果。如果需要进一步分析，可在处理后将输出传递给 AI。

示例场景：

• 在 Claude、Cursor、Cline 等 MCP 客户端中，用户上传报告、手册或方案 PDF，先将其转换为 Markdown 或 Word，然后让 AI 进行摘要、知识问答或内容重组
• 在处理发票、报表、扫描表格和图像附件的 MCP 工作流中，用户先提取表格和结构化数据，再进行财务审核、数据录入或自动路由
• 在 Agent 工作流中整理合同、投标文件、报价单或归档文件时，用户先合并、拆分、添加水印并转换 PDF，然后交给 AI 进行整理、命名或准备外发
• 在多步骤自动化工作流中，用户先将 PDF 或图像文件转换为轻量级 CSV、JSON 或 TXT 输出，再让下游 Agent 处理字段规范化、审批流程、知识库导入或脚本编排

示例提示词：

• 将此 PDF 转换为 Word，并尽可能保留版式。
• 提取此 PDF 中的所有表格，并导出为 CSV。
• 将此图像转换为 JSON，并返回结构化内容。
• 合并这些 PDF，添加水印，并返回最终文件。
• 先将此报告转换为 Markdown，然后总结要点。

---

由 ComPDF 团队打造。
网站 · 联系销售 · 技术支持