Pdf MCP

pdf mcp

](https://pypi.org/project/pdf-mcp/)   ](https://github.com/jztan/pdf-mcp/issues)   ](https://pepy.tech/project/pdf-mcp)

A. 模型上下文协议 （MCP）服务器，使AI代理能够读取、搜索和提取PDF文件中的内容。使用Python和PyMuPDF构建，具有基于SQLite的缓存，可在服务器重启时保持持久性。

mcp名称：io.github.jztan/pdf-mcp

在浏览器中尝试

查看您的AI代理所看到的内容→

浏览三个主要工具(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"}'

命令选项板：

1. 打开命令选项板(Cmd/Ctrl+Shift+P)
2. 跑 MCP: Open User Configuration （全球）或 MCP: Open Workspace Folder Configuration （项目特定）
3. 添加配置：

   {
     "servers": {
       "pdf-mcp": {
         "command": "pdf-mcp"
       }
     }
   }

1. 保存。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 消费。

示例提示：

"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

缓存的内容：

缓存无效：

• 文件修改时间更改时自动
• 手册通过 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？

路线图

看 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在各种查询类型中获胜