PDF Manipulation Toolkit

PDF MCP 服务

通过与 Claude 集成，使用 AI 驱动的自然语言命令，轻松处理 PDF

功能全面的 PDF 工具包，可通过 MCP（Model Context Protocol）与 Claude AI 无缝集成。使用简单的对话式命令执行复杂的 PDF 操作——轻松合并、拆分、加密、优化和分析 PDF。

🚀 快速开始

克隆并设置

git clone https://github.com/Sohaib-2/pdf-mcp-server.git
cd pdf-mcp-server

选项 1：使用虚拟环境（推荐）

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux  
source .venv/bin/activate

pip install -r requirements.txt

选项 2：不使用虚拟环境

pip install fastmcp requests pathlib

安装 PDF 工具

PDFtk：

# Ubuntu/Debian
sudo apt-get install pdftk
# macOS
brew install pdftk-java
# Windows: Download from https://www.pdflabs.com/tools/pdftk-the-pdf-toolkit/

QPDF：

# Ubuntu/Debian
sudo apt-get install qpdf
# macOS
brew install qpdf
# Windows: Download from https://qpdf.sourceforge.io/

🔧 Claude Desktop 集成

1. 找到 Claude 配置文件：

   • Windows： %APPDATA%\Claude\claude_desktop_config.json
   • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

2. 添加 PDF MCP 服务：

使用虚拟环境：

{
  "mcpServers": {
    "pdf-tools": {
      "command": "C:\\path\\to\\pdf-mcp-server\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\pdf-mcp-server\\server.py"]
    }
  }
}

不使用虚拟环境：

{
  "mcpServers": {
    "pdf-tools": {
      "command": "python",
      "args": ["C:\\path\\to\\pdf-mcp-server\\server.py"]
    }
  }
}

macOS/Linux 使用 venv：

{
  "mcpServers": {
    "pdf-tools": {
      "command": "/path/to/pdf-mcp-server/.venv/bin/python",
      "args": ["/path/to/pdf-mcp-server/server.py"]
    }
  }
}

3. 重启 Claude Desktop

4. 开始使用自然语言：

   • “将这 3 个 PDF 合并为一个文档”
   • “为我的报告加密并设置密码保护”
   • “从这份手册中提取第 1–10 页”

📚 完整工具参考

核心操作

工具	描述	示例
merge_pdfs	合并多个 PDF	merge_pdfs(['doc1.pdf', 'doc2.pdf'], 'combined.pdf')
split_pdf	拆分为单独的页面	split_pdf('document.pdf', './pages/')
extract_pages	提取指定页面范围	extract_pages('book.pdf', '1-5,10,15-20', 'excerpt.pdf')
rotate_pages	按角度旋转页面	rotate_pages('scan.pdf', '90', 'rotated.pdf', '1-3')

安全与加密

工具	描述	示例
encrypt_pdf	AES-256 加密	encrypt_pdf('file.pdf', 'secure.pdf', 'password123')
encrypt_pdf_basic	基本密码保护	encrypt_pdf_basic('doc.pdf', 'protected.pdf', 'pass', 'admin')
decrypt_pdf	移除密码保护	decrypt_pdf('locked.pdf', 'unlocked.pdf', 'password')

优化与修复

工具	描述	示例
optimize_pdf	为网页/电子邮件压缩	optimize_pdf('large.pdf', 'small.pdf', 'high')
repair_pdf	修复损坏的 PDF	repair_pdf('broken.pdf', 'fixed.pdf')
check_pdf_integrity	验证 PDF 结构	check_pdf_integrity('suspicious.pdf')

信息与分析

工具	描述	示例
get_pdf_info	详细元数据（JSON）	get_pdf_info('document.pdf')
update_pdf_metadata	修改标题、作者等	update_pdf_metadata('file.pdf', 'updated.pdf', title='New Title')
inspect_pdf_structure	分析内部结构	inspect_pdf_structure('complex.pdf', detailed=True)
extract_pdf_attachments	提取嵌入文件	extract_pdf_attachments('portfolio.pdf', './attachments/')

文件管理

工具	描述	示例
download_pdf	从 URL 下载	download_pdf('https://example.com/file.pdf', 'local.pdf')
open_pdf_preview	使用系统查看器打开	open_pdf_preview('report.pdf', browser=False)
get_file_info	文件大小／路径详情	get_file_info('document.pdf')
configure_pdf_workspace	设置工作目录	configure_pdf_workspace('/path/to/workspace')
count_pdfs_in_directory	列出文件夹中的 PDF	count_pdfs_in_directory('./pdf_folder/')

系统管理

工具	描述	用途
get_server_status	检查工具是否可用	验证 PDFtk／QPDF 是否已安装
list_default_directories	显示搜索路径	调试文件解析问题
get_pdf_tools_help	完整文档	应用内帮助参考

💬 自然语言示例

文档管理：

• “将我的所有研究论文合并为一份参考书目”
• “将这份 100 页的手册拆分成多个章节”
• “提取第 2–4 页的执行摘要”

安全操作：

• “使用军用级保护加密这份合同”
• “移除此锁定文档的密码”
• “添加所有者权限以防止编辑”

文件优化：

• “优化我下载文件夹中的所有 PDF”
• “修复这份损坏的演示文稿文件”

高级分析：

• “显示这篇学术论文的详细元数据”
• “分析内部结构以进行安全审计”

🗂️ 文件路径处理

灵活的路径解析：

• 绝对路径： C:\Documents\file.pdf
• 相对路径： ../pdfs/document.pdf
• 仅文件名： report.pdf（搜索默认目录）

默认搜索顺序：

1. PDF_WORKSPACE 环境变量
2. ~/Documents/PDFs
3. ~/Downloads
4. ~/Desktop
5. 当前工作目录

⚙️ 配置

自定义工作区：

configure_pdf_workspace('/path/to/your/pdfs')

检查安装：

get_server_status()  # Verify PDFtk and QPDF availability

🛠️ 故障排除

常见问题：

问题	解决方案
PDFtk not found	安装 PDFtk 并将其添加到 PATH
QPDF error	通过包管理器安装 QPDF
File not found	使用 list_default_directories() 检查搜索路径
Permission denied	使用适当的文件权限运行
Invalid PDF	使用 check_pdf_integrity() 验证文件

调试命令：

get_server_status()           # Check tool installation
list_default_directories()    # Verify search paths  
get_pdf_info('file.pdf')      # Validate PDF structure

🏗️ 架构

pdf-mcp-server/
├── server.py              # FastMCP server with 16 tools
├── pdftk_tools.py         # PDFtk CLI wrapper
├── qpdf_tools.py          # QPDF CLI wrapper  
├── utils.py               # File utilities & path resolution
└── requirements.txt       # Python dependencies

构建所用技术：

• FastMCP - MCP 服务框架
• PDFtk - PDF 处理
• QPDF - 高级 PDF 处理

🤝 贡献

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add amazing feature'
4. 推送到分支：git push origin feature/amazing-feature
5. 发起 Pull Request

📄 许可证

本项目基于 MIT License 授权

👨‍💻 作者

Sohaib-2 - GitHub

🌟 致谢

• 感谢 Anthropic 推出 MCP Protocol
• 感谢 PDFtk 和 QPDF 团队
• 感谢开源社区带来的灵感

---

⭐ 如果此仓库对你有帮助，请为它点亮星标！ | 🐛 报告问题 | 💡 请求功能