PDF Manipulation MCP Server

PDF操作MCP服务器

📚 该项目完全基于 PyMuPDF -一个用于PDF操作的强大Python库。请查看PyMuPDF官方文档，了解更多关于其广泛功能的信息！

一个实施模型上下文协议（MCP）服务器的研究项目，该服务器使用官方的MCP FastMCP框架提供全面的PDF操作功能。该项目侧重于用于学习和实验目的的直接PDF编辑和操作功能。

快速入门： 直接与 uv run pdf-manipulation-mcp-server （就像Node.js包的npx）

特性

• 文本操作：添加、替换和操作PDF中的文本
• 图像操作：添加图像并从PDF中提取图像
• 注释：添加各种类型的注释（文本、突出显示、下划线等）
• 表单字段：添加和填写表单字段
• 页面操作：合并、拆分、旋转、删除和裁剪页面
• 自动裁剪：自动检测和裁剪内容边界
• 页面组合：将多个页面组合成具有各种布局的单个页面
• 元数据：获取和设置PDF元数据

快速开始

先决条件

• Python 3.10+
• pip（Python自带）

📖 有关详细的安装说明，请参阅 安装.md

安装

选项1：直接使用UV（如npx）运行

# Run without installation (fastest)
uv run pdf-manipulation-mcp-server

选项2：从PyPI安装

# Install the package
pip install pdf-manipulation-mcp-server

# Run the server
pdf-mcp-server

选项3：从GitHub安装

# Install directly from GitHub
pip install git+https://github.com/yourusername/pdf-manipulation-mcp-server.git

# Run the server
pdf-mcp-server

选项4：本地克隆和安装

# Clone the repository
git clone https://github.com/yourusername/pdf-manipulation-mcp-server.git
cd pdf-manipulation-mcp-server

# Install in development mode
pip install -e .

# Run the server
pdf-mcp-server

选项5：使用UV（开发）

# Clone the repository
git clone https://github.com/yourusername/pdf-manipulation-mcp-server.git
cd pdf-manipulation-mcp-server

# Install dependencies with UV
uv pip install mcp pymupdf

# Test the server
uv run pytest tests/ -v

# Run the server
uv run python server.py

可用工具（共15个）

文本操作

• pdf_add_text -在指定位置向PDF添加文本
• pdf_replace_text -替换PDF文档中的文本

图像操作

• pdf_add_image -将图像添加到PDF
• pdf_extract_images -从PDF中提取所有图像

注释

• pdf_add_annotation -为PDF添加注释（文本、突出显示、下划线、删除线）

表单字段

• pdf_add_form_field -向PDF添加表单字段（文本、复选框、单选框、组合框）
• pdf_fill_form -用值填充PDF中的表单字段

页面操作

• pdf_merge_files -将多个PDF文件合并为一个
• pdf_combine_pages_to_single -将PDF中的多个页面合并为一个页面
• pdf_split -将PDF拆分为单独的页面或页面范围
• pdf_rotate_page -在PDF中旋转页面（90、180、270度）
• pdf_delete_page -从PDF中删除页面
• pdf_crop_page -使用坐标支持在PDF中裁剪页面
• pdf_auto_crop_page -通过检测内容边界自动裁剪页面

元数据

• pdf_get_info -获取PDF的元数据和信息
• pdf_set_metadata -为PDF设置元数据

如何使用Cursor IDE进行配置

步骤1：安装服务器

按照上述安装步骤设置MCP服务器。

步骤2：配置游标IDE

将此配置添加到光标设置中：

选项A：使用MCP配置和uvx：

创建 ~/.cursor/mcp_config.json:

{
  "mcpServers": {
    "pdf-manipulation": {
      "command": "uvx",
      "args": ["--from", "pdf-manipulation-mcp-server", "pdf-mcp-server"]
    }
  }
}

选项B：使用本地安装的MCP配置文件

创建 ~/.cursor/mcp_config.json:

{
  "mcpServers": {
    "pdf-manipulation": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "/path/to/pdf-manipulation-mcp-server"
    }
  }
}

选项C：使用光标设置UI

1. 打开光标设置(Cmd+, 在Mac上， Ctrl+, 在Windows/Linux上）
2. 在设置中搜索“MCP”
3. 添加此配置：

{
  "mcp.servers": {
    "pdf-manipulation": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "/path/to/pdf-manipulation-mcp-server"
    }
  }
}

步骤3：重新启动Cursor IDE

添加配置后，重新启动Cursor IDE以加载MCP服务器。

步骤4：测试集成

1. 在Cursor中打开新聊天
2. 尝试以下命令：

- “将此PDF转换为Markdown” - “向PDF添加文本” - “从PDF中提取图像” - “合并多个PDF”

用法示例

基本PDF自动裁剪工作流程

# Automatically crop PDF pages to remove margins
result = await pdf_auto_crop_page(
    pdf_path="document.pdf",
    padding=10.0
)

# Crop specific page with coordinates
result = await pdf_crop_page(
    pdf_path="document.pdf",
    page_number=0,
    x0=50, y0=50, x1=400, y1=300,
    coordinate_mode="bbox"
)

向PDF添加文本

result = await pdf_add_text(
    pdf_path="document.pdf",
    page_number=0,
    text="New text content",
    x=100,
    y=100,
    font_size=14,
    color=[1, 0, 0]  # Red color
)

处理图像

# Add image to PDF
result = await pdf_add_image(
    pdf_path="document.pdf",
    page_number=0,
    image_path="image.png",
    x=100,
    y=200,
    width=200,
    height=150
)

# Extract all images from PDF
result = await pdf_extract_images(
    pdf_path="document.pdf",
    output_dir="extracted_images"
)

页面操作

# Merge multiple PDFs
result = await pdf_merge_files(
    pdf_paths=["doc1.pdf", "doc2.pdf", "doc3.pdf"]
)

# Combine pages from a single PDF
result = await pdf_combine_pages_to_single(
    pdf_path="document.pdf",
    page_numbers=[0, 1, 2],
    layout="vertical"
)

# Split PDF into individual pages
result = await pdf_split(
    pdf_path="document.pdf",
    output_dir="split_pages"
)

# Rotate a page
result = await pdf_rotate_page(
    pdf_path="document.pdf",
    page_number=0,
    rotation=90
)

发展

项目结构

pdf-manipulation-mcp-server/
├── pdf_server.py          # Main MCP server implementation
├── server.py              # Entry point for UV
├── test_mcp_server.py     # Test script
├── pyproject.toml         # Project configuration
├── install.sh             # Installation script (Mac/Linux)
├── install.bat            # Installation script (Windows)
└── README.md              # This file

运行测试

# Test the MCP server
uv run python test_mcp_server.py

# Run the server
uv run python server.py

依赖项

• mcp -Python官方MCP SDK
• pymupdf -核心PDF操作库
• pytest -测试框架（开发依赖性）
• pytest-asyncio -异步测试支持（开发依赖性）

文件安全

所有操作都会创建带有时间戳的新文件，以避免覆盖原始文件。输出文件遵循以下模式： {original_name}_{operation}_{timestamp}.pdf

错误处理

服务器包括全面的错误处理：

• 操作前验证PDF文件
• 检查页码和坐标
• 提供清晰的错误消息
• 优雅地处理丢失的文件
• 捕获并报告PyMuPDF异常

故障排除

常见问题

1. 光标设置中的“无工具”：这很正常！工具出现在聊天界面中，而不是设置中。

1. 未找到UV：首先安装UV：

   curl -LsSf https://astral.sh/uv/install.sh | sh

1. Python版本错误：如果需要，UV将自动安装Python 3.11+。

1. 未找到依赖项：确保你使用的是紫外线：

   uv pip install mcp pymupdf

调试模式

要在调试模式下运行服务器，请执行以下操作：

uv run python server.py --debug

贡献

这是一个研究项目，但欢迎投稿！如果你想贡献：

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 测试用 uv run pytest tests/ -v
5. 提交拉取请求

研究项目说明

这个项目是作为一个学习练习而创建的，目的是探索：

• 模型上下文协议（MCP）服务器开发
• 使用PyMuPDF操作PDF
• FastMCP框架实施
• 使用pytest进行自动化测试
• 内容检测和裁剪算法

许可证

这个项目是开源的，可以在MIT许可证下使用。

支持

对于问题和疑问：

1. 检查上面的故障排除部分
2. 查看测试输出： uv run python test_mcp_server.py
3. 检查光标日志中的MCP错误
4. 在GitHub上打开一个问题