Pymupdf4llm Enhanced MCP

PyMuPDF4LLM Enhanced MCP

基于 PyMuPDF4LLM 和 Tiktoken 的 PDF 解析与分块 MCP 服务器。

功能特性

• 🔍 PDF 转 Markdown 格式
• 📊 基于 Token 的智能分块（使用 Tiktoken o200k_base）
• 💾 SHA256 哈希缓存机制
• 🔄 可配置的块重叠
• 📡 完整 MCP 协议支持

Claude Code 配置

claude mcp add -s local pymupdf4llm-enhanced pymupdf4llm-enhanced-mcp

使用方法

parse_pdf - 解析 PDF

将 PDF 转换为 Markdown 并分块。

parse_pdf(
    file_path="/path/to/document.pdf",
    chunk_size_tokens=2000,
    chunk_overlap_tokens=200
)
# 返回: {"chunks_count": 15, "cached": false}

read_chunk - 读取分块

从缓存读取指定分块。

read_chunk(
    file_path="/path/to/document.pdf",
    chunk_index=0
)
# 返回: {"chunk_index": 0, "content": "...", "file_path": "..."}

工作原理

1. 计算 PDF 文件的 SHA256 哈希值
2. 转换为 Markdown 并按 Token 数分块
3. 缓存到 .pymupdf4llm-enhanced-mcp/ 目录
4. 文件变更时自动重建缓存

使用场景

• 大型文档分析：处理长篇论文、技术手册
• RAG 系统：为检索增强生成准备文档块
• 批量处理：高效处理多个相同文档的查询

最佳实践

• 块大小：根据 LLM 上下文窗口设置（1000-3000 tokens）
• 重叠率：建议 10-15% 保持上下文连贯性
• 缓存管理：定期清理旧缓存释放空间

常见问题

Q: 缓存占用过大 A: 删除 .pymupdf4llm-enhanced-mcp/ 目录

Q: PDF 返回空内容 A: 检查 PDF 是否损坏或需要 OCR

相关链接

• MCP 协议
• PyMuPDF4LLM
• Tiktoken