pdf mcp
A. 模型上下文协议 （MCP）服务器，使AI代理能够读取、搜索和提取PDF文件中的内容。使用Python和PyMuPDF构建，具有基于SQLite的缓存，可在服务器重启时保持持久性。
mcp名称：io.github.jztan/pdf-mcp
在浏览器中尝试
浏览三个主要工具(pdf_info, pdf_search, pdf_read_pages)任何PDF。100%客户端，无需安装。
[](https://pdf-mcp.jztan.com/)
特性
为您的代理提供PDF的外科手术访问权限，而不是用原始文本淹没上下文。
- 混合搜索 --查找有问题的相关页面，而不是页面范围。通过互序融合将BM25关键字和语义搜索相结合
- 分页阅读 --只获取代理需要的页面；大型文档不会破坏您的上下文窗口
- 光学字符识别 --通过Tesseract，扫描和基于图像的PDF是完全可读和可搜索的
- 结构化提取 --表、嵌入式图像和目录作为结构化数据返回，而不是文本汤
- 持久缓存 --SQLite支持；重新读取是即时的，并且在服务器重启后仍然有效
- 安全URL获取 --仅支持HTTPS和SSRF保护；本地网络范围被阻止
安装
pip install pdf-mcp用于语义搜索（添加 fastembed 和 numpy，首次使用时下载约67 MB型号）：
pip install 'pdf-mcp[semantic]'对于扫描的PDF的OCR（需要Tesseract系统）：
# macOS
brew install tesseract
# Ubuntu/Debian
apt install tesseract-ocr
# Windows — download the installer from:
# https://github.com/UB-Mannheim/tesseract/wiki
# Then add the install directory to your PATH.快速开始
从下面选择您的MCP客户端开始：
Claude Code
claude mcp add pdf-mcp -- pdf-mcp或添加到 ~/.claude.json:
{
"mcpServers": {
"pdf-mcp": {
"command": "pdf-mcp"
}
}
}Claude Desktop
添加到您的 claude_desktop_config.json:
{
"mcpServers": {
"pdf-mcp": {
"command": "pdf-mcp"
}
}
}配置文件位置：
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json - 窗户：
%APPDATA%\Claude\claude_desktop_config.json
更新配置后重新启动Claude Desktop。
Visual Studio Code
需要使用GitHub Copilot的VS代码1.101+。
CLI：
code --add-mcp '{"name":"pdf-mcp","command":"pdf-mcp"}'命令选项板：
- 打开命令选项板(
Cmd/Ctrl+Shift+P) - 跑
MCP: Open User Configuration（全球）或MCP: Open Workspace Folder Configuration（项目特定） - 添加配置：
{
"servers": {
"pdf-mcp": {
"command": "pdf-mcp"
}
}
}- 保存。VS Code将自动加载服务器。
手册： 创建 .vscode/mcp.json 在您的工作空间中：
{
"servers": {
"pdf-mcp": {
"command": "pdf-mcp"
}
}
}Codex CLI
codex mcp add pdf-mcp -- pdf-mcp或在中手动配置 ~/.codex/config.toml:
[mcp_servers.pdf-mcp]
command = "pdf-mcp"Kiro
创建或编辑 .kiro/settings/mcp.json 在您的工作空间中：
{
"mcpServers": {
"pdf-mcp": {
"command": "pdf-mcp",
"args": [],
"disabled": false
}
}
}保存并重新启动Kiro。
Other MCP Clients
大多数MCP客户端使用标准配置格式：
{
"mcpServers": {
"pdf-mcp": {
"command": "pdf-mcp"
}
}
}随着 uvx （适用于隔离环境）：
{
"mcpServers": {
"pdf-mcp": {
"command": "uvx",
"args": ["pdf-mcp"]
}
}
}验证安装
pdf-mcp --help工具
八个专门的工具涵盖了文档自检、内容读取、搜索和缓存管理。典型模式：呼叫 pdf_info 先计划，然后 pdf_search 定位，然后 pdf_read_pages 或 pdf_read_all 消费。
| 工具 | 它做什么 |
|---|---|
pdf_info | 页面计数、元数据、TOC摘要、扫描页面检测。 先打电话。 |
pdf_get_toc | 包含50个以上书签的文档的完整目录 |
pdf_read_pages | 阅读特定的页面或范围；按需OCR；嵌入式图像+表格 |
pdf_read_all | 在一次调用中读取整个文档（为安全起见，以字节为上限） |
pdf_render_pages | 将页面渲染为视觉模型的PNG格式——图表、手写、扫描 |
pdf_search | 混合RRF搜索（关键字+语义），页面或部分粒度 |
pdf_cache_stats | 每个文档缓存细分+总大小 |
pdf_cache_clear | 清除过期或所有缓存条目 |
示例提示：
"Read the PDF at /path/to/document.pdf"
"Which pages discuss supply chain risks?"
"Find sections about the training process"
"Show me what page 5 looks like"
"OCR pages 3-5 of the scanned PDF"看 docs/tool-reference.md 完整的参考——每个参数、响应形状、安全契约和示例。关于语义搜索模型的选择，请参见 docs/embedding-models.md.
工作流示例
对于大型文件（例如，200页的年度报告）：
User: "Summarize the risk factors in this annual report"
Agent workflow:
1. pdf_info("report.pdf")
→ 200 pages, TOC shows "Risk Factors" on page 89
2. pdf_search("report.pdf", "risk factors")
→ Relevant pages: 89-110
3. pdf_read_pages("report.pdf", "89-100")
→ First batch
4. pdf_read_pages("report.pdf", "101-110")
→ Second batch
5. Synthesize answer from chunks缓存
服务器使用SQLite进行持久缓存。这是必要的，因为使用STDIO传输的MCP服务器是作为每个会话的新进程生成的。
缓存位置： ~/.cache/pdf-mcp/cache.db
缓存的内容：
| 数据 | 好处 |
|---|---|
| 元数据+文本覆盖率 | 避免重新解析文档信息 |
| 页面文本 | 跳过重新提取 |
| 图像 | 跳过重新编码 |
| 表 | 跳过重新检测 |
| TOC | 跳过重新解析 |
| FTS5索引 | O（log N）搜索，首次查询后BM25排名 |
| 嵌入 | 首次索引运行后的即时语义搜索 |
| 渲染的PNG | 跳过重新渲染；共享之间 pdf_render_pages 和 pdf_read_pages(render_dpi=…) |
缓存无效：
- 文件修改时间更改时自动
- 手册通过
pdf_cache_clear工具 - TTL：24小时（可配置）
配置
访问控制（可选）
创建 ~/.config/pdf-mcp/config.toml 以限制服务器将访问哪些本地路径和URL主机。该文件是可选的——如果不存在，服务器在内置的SSRF地板内是允许的（仅HTTPS，被阻止的私有IP范围）。
[paths]
allow = ["~/Documents/**", "/data/pdfs/**"]
deny = ["~/.ssh/**", "~/.aws/**"]
[urls]
allow = ["*.internal.example.com"]
deny = ["untrusted.example.com"]
[limits]
max_response_bytes = 200000这 [limits] 块将文本有效负载字节大小限制在 pdf_read_all 以及分段粒度 pdf_search --看 docs/response-limits.md规则使用shell glob模式(* 跨路径分隔符匹配）。 deny 当双方比赛时获胜。路径匹配在符号链接扩展后对解析的路径进行操作。格式错误的配置文件会阻止服务器启动——它永远不会悄无声息地回到许可状态。
环境变量
# Cache directory (default: ~/.cache/pdf-mcp)
PDF_MCP_CACHE_DIR=/path/to/cache
# Cache TTL in hours (default: 24)
PDF_MCP_CACHE_TTL=48发展
git clone https://github.com/jztan/pdf-mcp.git
cd pdf-mcp
# Install with dev dependencies
pip install -e ".[dev]"
# One-time: install pre-commit hooks (auto-runs black/flake8/mypy on commit)
pre-commit install
# Run tests
pytest tests/ -v
# Type checking
mypy src/
# Linting
flake8 src/ tests/
# Formatting
black src/ tests/为什么选择pdf mcp？
| 没有pdf mcp | 有pdf mcp | |
|---|---|---|
| 大型PDF文档 | 上下文溢出 | 阅读受阻 |
| 代币预算 | 猜测和溢出 | 阅读前估计的代币 |
| 查找内容 | 加载所有内容 | 混合搜索——BM25关键字（FTS5）+语义嵌入的RRF融合；永远不会错过任何一个人都会错过的东西 |
| 表格 | 原始文本中丢失 | 每页提取和内联 |
| 图像 | 忽略 | 提取为PNG文件 |
| 重复访问 | 每次重新解析 | SQLite缓存 |
| 扫描PDF | 未提取文本 | 通过Tesseract进行OCR(pdf_read_pages(ocr=True)) |
| 视觉内容 | 必须用文字描述 | 将页面渲染为图像(pdf_render_pages) |
| 刀具设计 | 单片刀具 | 8个专用刀具 |
路线图
看 ROADMAP.md 了解计划功能和发布历史。
贡献
欢迎捐款。请提交一个pull请求。
安全
发现漏洞？看 安全.md 威胁模型、报告渠道和预期响应时间线。请不要为未打补丁的安全报告打开公共GitHub问题。
许可证
麻省理工学院——见 许可证.
链接
- PyPI上的pdf mcp
- 如何构建pdf mcp --AI代理中大型PDF的问题和有效的解决方案
- MCP服务器安全：8个漏洞 --我们审计MCP服务器的安全漏洞时发现了什么
- Claude Code如何读取PDF --AI代理如何使用pdf-mcp工具阅读和浏览pdf文档
- 人工智能代理的语义搜索与关键字搜索 --基准和双搜索路由模式：FTS5用于精确标识符，嵌入用于自然语言
- 人工智能代理的混合搜索与查询路由 --为什么pdf-mcp使用混合RRF而不是查询路由：基准测试显示RRF在各种查询类型中获胜
