飞梭PDF-MCP服务器
项目介绍
Spire.PDF MCP Server 是什么？
Spire.PDF MCP Server 是一个模型上下文协议（MCP）服务器，它允许您通过您的AI代理直接创建、读取、编辑和转换PDF文档，无需依赖Adobe Acrobat或其他PDF软件。
它提供了广泛的PDF操作能力，包括合并、分割、替换文本、表单操作、添加水印和格式转换。
主要特性
- 从零开始创建PDF文档
- 修改现有的PDF文件（替换文本、添加水印、压缩等）
- 转换PDF到Word、PDF到Excel、PDF到HTML等
- 合并和分割PDF文件
- 加密和解密PDF文档
- 展平表单字段并提取表单值
- 删除或展开PDF书签
- 从PDF文件中删除附件
快速入门
先决条件
- Python 3.10 或更高版本
安装
- 克隆仓库：
git clone https://github.com/eiceblue/spire-pdf-mcp-server.git
cd spire-pdf-mcp-server
- 使用uv安装：
uv pip install -e .
运行服务器
启动服务器（默认端口8000）：
uv run spire-pdf-mcp-server
自定义端口（例如，8080）：
# Bash/Linux/macOS
export FASTMCP_PORT=8080 && uv run spire-pdf-mcp-server
# Windows PowerShell
$env:FASTMCP_PORT = "8080"; uv run spire-pdf-mcp-server
与AI工具集成
Cursor IDE
- 在Cursor中添加此配置：
{
"mcpServers": {
"pdf": {
"url": "http://localhost:8000/sse",
"env": {
"PDF_FILES_PATH": "/path/to/pdf/files"
}
}
}
}
- 您可以通过AI助手访问PDF工具。
远程托管及协议
该服务器使用**服务发送事件（SSE）**传输协议。 对于其他环境：
- Claude Desktop（需要stdio）：使用Supergateway将SSE转换为stdio。
- 远程托管：遵循远程MCP服务器指南。
环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
FASTMCP_PORT | 服务器端口 | 8000 |
PDF_FILES_PATH | PDF文件目录 | ./pdf_files |
可用工具
服务器提供15+工具，分为5类：
文档操作（10个工具）
- create_pdfducoment：创建新的PDF文档
- convert_pdfdocument：将PDF转换为其他格式（Word、Excel、HTML、图像、PDF/A等）
- extract_text：从PDF页面中提取文本
- merge_pdfs：将多个PDF合并为一个
- add_text_watermark：在PDF中插入文本水印
- compress_document：减少PDF文件大小
- split_document：将PDF拆分为多个文件
- encrypt_document：对PDF应用密码保护
- decrypt_document：移除密码保护
- replace_all_text：替换PDF中的所有匹配文本
书签操作（2个工具）
- delete_all_bookmarks：从PDF中删除所有书签
- expand_bookmarks：展开书签树
表单操作（2个工具）
- flatten_formfield：展平PDF中的表单字段
- get_forms_values：从PDF表单中提取值
附件操作（1个工具）
- delete_all_attachments：从PDF中删除所有附件
支持的转换格式
- DOC/DOCX：Microsoft Word
- XLS/XLSX：Microsoft Excel
- PPTX：Microsoft PowerPoint
- HTML：超文本标记语言
- SVG：可缩放矢量图形
- 图像格式：PNG、JPG、BMP等
- PDF/A (1a, 1b, 2a, 2b, 3a, 3b)：存档PDF
- PDF/X-1a:2001：印刷行业标准
- XPS, PCL, Markdown, Gray PDF, Linearized PDF
开发
项目结构
spire-pdf-mcp-server/
├── src/spire_pdf_mcp/
│ ├── api/ # API层（工具）
│ │ ├── document_tools.py
│ │ ├── bookmarks_tools.py
│ │ ├── forms_tools.py
│ │ ├── attachments_tools.py
│ ├── core/ # 核心业务逻辑
│ │ ├── document.py
│ │ ├── bookmarks.py
│ │ ├── forms.py
│ │ ├── attachments.py
│ │ └── base.py
│ ├── utils/ # 工具和常量
│ │ ├── exceptions.py
│ │ └── constants.py
│ ├── server.py # MCP服务器实现
│ └── __main__.py # 入口点
├── pyproject.toml # 项目配置
├── README.md # 此文件
└── TOOLS.md # 详细的工具文档
运行测试
uv run pytest
代码质量
- 完全使用Python类型提示
- 全面的错误处理
- 模块化架构
- 一致的代码格式
- 详细的内联文档
文档
- TOOLS.md：带有使用示例的完整工具文档
- 错误处理：常见错误和故障排除
🤝 贡献
- 分叉仓库
- 创建功能分支
- 提交更改
- 添加适用的测试
- 提交拉取请求
许可证
本项目采用MIT许可证——详情见LICENSE文件。
版本历史
- v1.0.0：初始稳定版，附带工具
- 完整的PDF文档操作能力
- 全面的错误处理
- 完整的格式转换支持