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 服務器的安全經驗

🤝 貢獻

歡迎貢獻代碼，請提交拉取請求。