星战科技xingzhan.cloud
返回市场
PDF操作MCP服务器

PDF操作MCP服务器

作者：andr3medeiros2 星标更新：2025-11-10
安装使用来源：spider==github.com

项目介绍

PDF 操作 MCP 服务器

📚 本项目完全基于 PyMuPDF —— 一个强大的用于 PDF 操作的 Python 库。请参阅官方 PyMuPDF 文档以了解其广泛的特性！

这是一个研究项目，实现了使用官方 MCP FastMCP 框架提供全面 PDF 操作能力的 Model Context Protocol (MCP) 服务器。该项目专注于直接 PDF 编辑和操作功能，用于学习和实验目的。

<a href="https://glama.ai/mcp/servers/@andr3medeiros/pdf-manipulation-mcp-server"> <img width="380" height="200" src="https://gips2.baidu.com/it/u=2746350498,3189532852&fm=3081&app=3081&f=PNG?w=760&h=400" alt="PDF 操作 MCP 服务器" /> </a>

快速开始： 直接运行 uv run pdf-manipulation-mcp-server（类似于 Node.js 包中的 npx）

功能

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

快速开始

前提条件

  • Python 3.10+
  • pip（随 Python 一起提供）

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

安装

选项 1：直接使用 UV 运行（类似于 npx）

# 不需要安装即可运行（最快）
uv run pdf-manipulation-mcp-server

选项 2：从 PyPI 安装

# 安装包
pip install pdf-manipulation-mcp-server

# 运行服务器
pdf-mcp-server

选项 3：从 GitHub 安装

# 直接从 GitHub 安装
pip install git+https://github.com/yourusername/pdf-manipulation-mcp-server.git

# 运行服务器
pdf-mcp-server

选项 4：克隆并本地安装

# 克隆仓库
git clone https://github.com/yourusername/pdf-manipulation-mcp-server.git
cd pdf-manipulation-mcp-server

# 开发模式安装
pip install -e .

# 运行服务器
pdf-mcp-server

选项 5：使用 UV（开发）

# 克隆仓库
git clone https://github.com/yourusername/pdf-manipulation-mcp-server.git
cd pdf-manipulation-mcp-server

# 使用 UV 安装依赖
uv pip install mcp pymupdf

# 测试服务器
uv run pytest tests/ -v

# 运行服务器
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：配置 Cursor IDE

在你的 Cursor 设置中添加以下配置：

选项 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：使用 Cursor 设置 UI

  1. 打开 Cursor 设置（Mac 上为 Cmd+,，Windows/Linux 上为 Ctrl+,）
  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 自动裁剪工作流程

# 自动裁剪 PDF 页面以去除边距
result = await pdf_auto_crop_page(
    pdf_path="document.pdf",
    padding=10.0
)

# 使用坐标裁剪特定页面
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="新的文本内容",
    x=100,
    y=100,
    font_size=14,
    color=[1, 0, 0]  # 红色
)

处理图像

# 向 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
)

# 从 PDF 提取所有图像
result = await pdf_extract_images(
    pdf_path="document.pdf",
    output_dir="extracted_images"
)

页面操作

# 合并多个 PDF
result = await pdf_merge_files(
    pdf_paths=["doc1.pdf", "doc2.pdf", "doc3.pdf"]
)

# 将单个 PDF 中的页面组合成一页
result = await pdf_combine_pages_to_single(
    pdf_path="document.pdf",
    page_numbers=[0, 1, 2],
    layout="vertical"
)

# 将 PDF 分割为单独的页面
result = await pdf_split(
    pdf_path="document.pdf",
    output_dir="split_pages"
)

# 旋转页面
result = await pdf_rotate_page(
    pdf_path="document.pdf",
    page_number=0,
    rotation=90
)

开发

项目结构

pdf-manipulation-mcp-server/
├── pdf_server.py          # 主 MCP 服务器实现
├── server.py              # UV 入口点
├── test_mcp_server.py     # 测试脚本
├── pyproject.toml         # 项目配置
├── install.sh             # 安装脚本（Mac/Linux）
├── install.bat            # 安装脚本（Windows）
└── README.md              # 本文件

运行测试

# 测试 MCP 服务器
uv run python test_mcp_server.py

# 运行服务器
uv run python server.py

依赖项

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

文件安全

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

错误处理

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

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

故障排除

常见问题

  1. “Cursor 设置中没有工具”：这是正常的！工具出现在聊天界面中，而不是设置中。

  2. “未找到 UV”：首先安装 UV：

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

  3. “Python 版本错误”：如果需要，UV 会自动安装 Python 3.11+。

  4. “未找到依赖项”：确保你正在使用 UV：

    uv pip install mcp pymupdf

调试模式

要以调试模式运行服务器：

uv run python server.py --debug

贡献

这是一个研究项目，但欢迎贡献！如果你希望贡献：

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

学习项目笔记

这个项目作为学习练习创建，旨在探索：

  • Model Context Protocol (MCP) 服务器开发
  • 使用 PyMuPDF 操作 PDF
  • FastMCP 框架实现
  • 使用 pytest 进行自动化测试
  • 内容检测和裁剪算法

许可证

本项目是开源的，并且在 MIT 许可证下可用。

支持

对于问题和疑问：

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