PDF MCP Server

使用与Claude集成的AI自然语言命令来转换PDF操作

这是一个全面的PDF工具包，通过MCP（模型上下文协议）无缝集成到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: 从 https://www.pdflabs.com/tools/pdftk-the-pdf-toolkit/ 下载

QPDF:

# Ubuntu/Debian
sudo apt-get install qpdf
# macOS
brew install qpdf
# Windows: 从 https://qpdf.sourceforge.io/ 下载

🔧 Claude桌面集成

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 使用虚拟环境：

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

3. 重启Claude桌面

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='新标题')
inspect_pdf_structure	内部结构分析	inspect_pdf_structure('复杂.pdf', detailed=True)
extract_pdf_attachments	提取嵌入文件	extract_pdf_attachments('投资组合.pdf', './附件/')

文件管理

工具	描述	示例
download_pdf	从URL下载	download_pdf('https://example.com/file.pdf', '本地.pdf')
open_pdf_preview	使用系统查看器打开	open_pdf_preview('报告.pdf', browser=False)
get_file_info	文件大小/路径详情	get_file_info('文档.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
• 仅文件名: 报告.pdf（在默认目录中搜索）

默认搜索顺序：

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

⚙️ 配置

自定义工作区：

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

检查安装：

get_server_status()  # 验证PDFtk和QPDF可用性

🛠️ 故障排除

常见问题：

问题	解决方案
未找到PDFtk	安装PDFtk并添加到PATH
QPDF错误	通过包管理器安装QPDF
找不到文件	使用list_default_directories()检查搜索路径
权限被拒绝	使用适当的文件权限运行
无效PDF	使用check_pdf_integrity()验证文件

调试命令：

get_server_status()           # 检查工具安装
list_default_directories()    # 验证搜索路径  
get_pdf_info('file.pdf')      # 验证PDF结构

🏗️ 架构

pdf-mcp-server/
├── server.py              # 包含16个工具的FastMCP服务器
├── pdftk_tools.py         # PDFtk CLI封装
├── qpdf_tools.py          # QPDF CLI封装  
├── utils.py               # 文件实用程序及路径解析
└── requirements.txt       # Python依赖项

构建于：

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

🤝 贡献

1. 分叉仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m '添加精彩功能'
4. 推送到分支：git push origin feature/amazing-feature
5. 打开拉取请求

📄 许可证

此项目采用MIT许可证

👨‍💻 作者

Sohaib-2 - GitHub

🌟 致谢

• Anthropic 为MCP协议
• PDFtk 和 QPDF 团队
• 开源社区提供的灵感

---

⭐ 如果对你有帮助，请给这个仓库点个星！ | 🐛 报告问题 | 💡 请求功能