pdf-mcp Skill 技能

技能简介

pdf-mcp 是一个把「代理式检索增强生成」直接搬到 PDF 上的 MCP 服务器，让 Claude Code 等 AI 代理对单个 PDF 或整个文件夹做语义加关键词的混合检索，只读取真正相关的页面，而不是把几百页塞进上下文。它提供 13 个专用工具而非一个巨型工具：代理自己决定何时检索，pdf-mcp 负责执行召回并交回片段。无论是多栏学术论文、日文竖排排版、带表格的年报，还是纯扫描件，它都能按正确阅读顺序抽取内容，还支持 NVIDIA 卡上的 CUDA 向量加速，适合大规模文档语料。项目开源（MIT 协议），GitHub 获得 147 星，是 C 线少见的高成熟度文档检索类技能。

核心能力

• 混合检索：BM25 关键词加语义向量双路召回，支持按页或按章节粒度，返回带来源坐标的段落摘录，摘录常能直接回答问题。
• 文件夹级语料操作：pdf_corpus_overview 对整个文件夹做逐文档分诊卡片，pdf_corpus_search 跨全部文档统一搜索并标注出处，pdf_corpus_warm 在时间预算内预热缓存。
• 结构化内容抽取：表格还原为结构化行，矢量图表按几何读出精确的 (x, y) 数据表，多栏与日文竖排保持正确阅读顺序。
• 扫描件 OCR：通过 Tesseract 按页并行 OCR，让无文本层的扫描 PDF 也能被检索和阅读。
• 持久缓存与性能：SQLite 缓存跨重启保留，重复访问不重解析；预热采用按长度排序的小批量 CPU 编码，可选 CUDA 加速一到两个数量级。
• 内容信任标注：pdf_info(content_trust=True) 会报告人类肉眼看不到的隐藏文本，读取工具逐页标记可疑注入内容，只标注不静默删除。
• 13 工具协作：pdf_info 规划、pdf_search 定位、pdf_read_pages 深读，另有目录、整读、渲染 PNG、缓存管理等工具，职责单一便于代理编排。

安装配置

1. Claude Desktop 免命令行：从 GitHub Releases 下载 pdf-mcp.mcpb 安装包，在「设置 > 扩展」页拖入安装；首次启动会下载约 250MB 组件。
2. Claude Code 与通用 MCP 客户端：需 Python 3.10+，执行 uv tool install pdf-mcp（或 pipx install pdf-mcp），再用 claude mcp add pdf-mcp -- pdf-mcp 注册；VS Code、Cursor、Codex CLI 等按官方 clients 文档配置。
3. 扫描件 OCR 选配：系统安装 Tesseract（macOS 用 brew install tesseract，Ubuntu 用 apt install tesseract-ocr，Windows 用 winget），首次扫描页会自动下载英文语言包。
4. CUDA 加速选配：NVIDIA 显卡可开启 GPU 向量编码，大语料预热快一到两个数量级，详见官方 configuration 文档。

使用步骤

1. 安装注册：按上文方式安装并把 pdf-mcp 注册进你的 MCP 客户端。
2. 先查概况：让代理先调 pdf_info 获取页数、元数据、目录摘要与扫描页检测结果，据此规划阅读策略。
3. 检索定位：用 pdf_search 做混合搜索，段落级摘录往往直接给出答案；不够再用 pdf_read_pages 精读指定页或区间。
4. 文件夹多文档：先 pdf_corpus_warm 预热，再 pdf_corpus_overview 分诊，最后 pdf_corpus_search 跨文档搜索。
5. 提问示例：直接说「用 pdf-mcp 总结 /path/report.pdf」「哪些页讨论了供应链风险」「OCR 第 3-5 页扫描件」即可。

适用场景

• 超长文档问答：200 页年报只读取风险因素相关页，避免上下文溢出。
• 论文与资料库检索：跨整个文件夹按含义找内容，标注文档与页码出处。
• 扫描件数字化：合同、发票、档案的 OCR 检索与关键段落提取。
• 表格与图表取数：把报告表格和矢量图还原为可计算的结构化数据。
• 多栏与竖排排版：学术双栏论文、日文竖排书籍按正确顺序阅读。

适用人群

需要让 AI 处理大量 PDF 的研究人员与数据分析师；做合同、年报、档案数字化的法务与合规人员；希望给 Claude Code 等代理接入文档检索能力的开发者；处理扫描件与多语言排版文档的知识工作者。

工作原理

代理在需要时调用工具，pdf-mcp 执行检索并返回片段。预热阶段把 PDF 解析入 SQLite 缓存，文本建立 FTS5 关键词索引并生成本地向量（可选 CUDA）；检索时 BM25 与向量双路召回后融合排序，按页或章节粒度截取带来源坐标的摘录。读取页面时按需触发 OCR、表格解析与图表几何抽取，多栏与竖排版面按阅读顺序重建。缓存跨重启生效，隐藏或注入文本经信任标注流程报告给代理而非静默吞掉。

官方链接

• GitHub 仓库：https://github.com/jztan/pdf-mcp
• PyPI 主页：https://pypi.org/project/pdf-mcp/
• 在线演示：https://pdf-mcp.jztan.com/