Pdf MCP

🚀 pdf-mcp

pdf-mcp 是一个基于 模型上下文协议（MCP）的服务器，它能让 AI 代理读取、搜索和提取 PDF 文件中的内容。该项目使用 Python 和 PyMuPDF 构建，并采用基于 SQLite 的缓存机制，确保服务器重启后数据依然持久化。

🚀 快速开始

安装

pip install pdf-mcp

验证安装

pdf-mcp --help

不同客户端配置示例

claude mcp add pdf-mcp -- pdf-mcp

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

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

code --add-mcp '{"name":"pdf-mcp","command":"pdf-mcp"}'

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

codex mcp add pdf-mcp -- pdf-mcp

[mcp_servers.pdf-mcp]
command = "pdf-mcp"

{
  "mcpServers": {
    "pdf-mcp": {
      "command": "pdf-mcp",
      "args": [],
      "disabled": false
    }
  }
}

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

{
  "mcpServers": {
    "pdf-mcp": {
      "command": "uvx",
      "args": ["pdf-mcp"]
    }
  }
}

✨ 主要特性

• 8 种专业工具：用于不同的 PDF 操作。
• SQLite 缓存：持久化缓存，服务器重启后依然保留（对 STDIO 传输至关重要）。
• 分页阅读：以可管理的块读取大型 PDF。
• 全文搜索：无需加载整个文档即可查找内容。
• 图像提取：将图像提取为 base64 编码的 PNG 格式。
• URL 支持：从 HTTP/HTTPS URL 读取 PDF。

💻 使用示例

工具使用示例

pdf_info — 获取文档信息

返回页面数量、元数据、目录、文件大小和估计的令牌数。建议先调用此工具，在阅读文档前了解其基本信息。

"Read the PDF at /path/to/document.pdf"

pdf_read_pages — 读取特定页面

读取选定的页面以管理上下文大小。

"Read pages 1-10 of the PDF"
"Read pages 15, 20, and 25-30"

pdf_read_all — 读取整个文档

一次读取完整的文档，但受页面数量的安全限制。

"Read the entire PDF (it's only 10 pages)"

pdf_search — 在 PDF 中搜索

在加载内容之前查找相关页面。

"Search for 'quarterly revenue' in the PDF"

pdf_get_toc — 获取目录

"Show me the table of contents"

pdf_extract_images — 提取图像

"Extract images from pages 1-5"

pdf_cache_stats — 查看缓存统计信息

"Show PDF cache statistics"

pdf_cache_clear — 清除缓存

"Clear expired PDF cache entries"

示例工作流程

对于大型文档（例如 200 页的年度报告）：

用户: "Summarize the risk factors in this annual report"

代理工作流程:
1. pdf_info("report.pdf")
   → 200 页，目录显示 "Risk Factors" 在第 89 页

2. pdf_search("report.pdf", "risk factors")
   → 相关页面: 89 - 110

3. pdf_read_pages("report.pdf", "89-100")
   → 第一批

4. pdf_read_pages("report.pdf", "101-110")
   → 第二批

5. 从各部分内容合成答案

🔧 技术细节

缓存机制

服务器使用 SQLite 进行持久化缓存。这是必要的，因为使用 STDIO 传输的 MCP 服务器会为每个对话生成一个新进程。

缓存位置：~/.cache/pdf-mcp/cache.db

缓存内容：

缓存失效机制：

• 文件修改时间改变时自动失效
• 可通过 pdf_cache_clear 工具手动清除
• 缓存过期时间（TTL）：24 小时（可配置）

配置

可通过环境变量进行配置：

# 缓存目录（默认：~/.cache/pdf-mcp）
PDF_MCP_CACHE_DIR=/path/to/cache

# 缓存过期时间（小时，默认：24）
PDF_MCP_CACHE_TTL=48

开发

git clone https://github.com/jztan/pdf-mcp.git
cd pdf-mcp

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/ -v

# 类型检查
mypy src/

# 代码检查
flake8 src/

# 代码格式化
black src/

选择 pdf-mcp 的理由

📄 许可证

本项目采用 MIT 许可证，详情请见 LICENSE。

📚 详细文档

• PyPI
• GitHub
• MCP 文档
• How I Built pdf-mcp — 项目背后的故事
• MCP Server Security: 8 Vulnerabilities — 构建 MCP 服务器的安全经验

🤝 贡献

欢迎贡献代码，请提交拉取请求。