PDF编辑MCP服务器
一个使用PyMuPDF（fitz）实现的PDF编辑模型上下文协议（MCP）服务器。该服务器提供了加载PDF文件、识别并编辑敏感文本以及保存编辑后的文档的工具。
特性/特点
- 📄 代表一张纸或文档的符号。 加载并阅读PDF文件 - 从PDF中提取文本内容以供审阅
- 🔍 看起来像是放大镜的符号，通常用于表示查看、搜索或放大查看某物。在中文中，可以简单地翻译为“🔍（放大镜）”或者根据上下文，用“查看”、“搜索”或“放大查看”等词来表达其含义。 批量文本编辑 - 一次性搜索并编辑多个文本字符串，以实现最大效率
- 📋 翻译为中文是：清单/条目列表。 编辑跟踪 - 记录已编辑过的内容，以避免重复工作
- 🔎（放大镜图标，通常表示搜索或查看细节） 列出已应用的编辑 - 审计追踪，显示哪些文本已被标记为需删除
- 尺子 基于区域的编辑或修改 - 通过坐标绘制特定的矩形区域
- 💾 磁盘/存储设备 保存已编辑过的PDF文件 - 应用编辑并自动命名保存
- 🎨（彩绘/艺术创作） 可自定义的编辑外观 - 选择修订填充颜色
- 🔒（锁形符号，通常表示安全、保密或锁定的状态） 错误处理 - 通过MCP协议提供全面的错误信息
安装
这个项目使用 uv 用于包管理。安装方法：
# Clone the repository
git clone
cd redact_mcp
# Install with uv
uv pip install -e .使用方法
运行服务器
你可以直接使用Python脚本或FastMCP命令行界面来运行服务器：
选项1：直接执行Python（标准I/O传输）
python -m redact_mcp.server选项2：使用FastMCP命令行界面（CLI）
# Stdio transport (default)
fastmcp run redact_mcp.server:mcp
# HTTP transport for remote access
fastmcp run redact_mcp.server:mcp --transport http --port 8000在MCP客户端上安装
Claude Desktop（可译为“Claude桌面版”或根据具体语境简化为“Claude桌面应用”）
在您的Claude桌面配置文件中添加：
macOS（苹果电脑操作系统）： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"pdf-redaction": {
"command": "uv",
"args": [
"--directory",
"/path/to/redact_mcp",
"run",
"fastmcp",
"run",
"redact_mcp.server:mcp"
]
}
}
}其他MCP客户端
使用 FastMCP CLI 为其他客户端生成配置：
# For Cursor
fastmcp install cursor redact_mcp.server:mcp
# For Gemini CLI
fastmcp install gemini-cli redact_mcp.server:mcp
# Generate generic MCP JSON configuration
fastmcp install mcp-json redact_mcp.server:mcp可用工具
1. load_pdf
加载一个PDF文件并提取其文本内容。
参数：
pdf_path（字符串）：要加载的PDF文件的路径
返回值： PDF的全文内容，按页面组织
示例：
Load the PDF at /path/to/document.pdf2. redact_text
在已加载的PDF中删除所有特定文本的实例。 这个工具现在可以同时处理多段文本 用于高效批量编辑。它会自动追踪哪些文本已经过编辑，以避免重复工作。
参数：
pdf_path(字符串)：已加载PDF文件的路径texts_to_redact（字符串列表）：要搜索并编辑的文本字符串列表fill_color(元组，可选)：遮蔽框的RGB颜色（0-1范围）。默认：(0, 0, 0) - 黑色
返回值： 编辑操作总结，包括哪些文本是新编辑的，哪些是跳过的（已编辑过的）
示例：
# Single text
Redact ["confidential"] in /path/to/document.pdf
# Multiple texts at once (recommended for efficiency)
Redact ["John Doe", "123-45-6789", "john.doe@email.com"] in /path/to/document.pdf注： 该工具会追踪哪些文本已被编辑，并会跳过任何已处理过的文本，以防止重复编辑。
3. redact_area
在PDF页面上划定一个特定的矩形区域。
参数：
pdf_path(字符串)：已加载PDF文件的路径page_number(int): 页码（从1开始计数）x0(float): 左边的x坐标y0(float): 顶部y坐标x1(float): 右侧x坐标y1(浮点数): 底部y坐标fill_color(元组，可选)：用于遮盖框的RGB颜色（0-1范围）。默认值：(0, 0, 0) - 黑色
返回值： 确认信息
示例：
Redact the area from (100, 100) to (300, 150) on page 1 of /path/to/document.pdf4. save_redacted_pdf
应用所有待处理的遮蔽内容并保存PDF文件。
参数：
pdf_path(字符串)：已加载PDF文件的路径output_path(字符串，可选)：自定义输出路径。如果未提供，则在原始文件名后追加“\_redacted”
返回： 保存的已编辑（或：已遮蔽）PDF文件的路径
示例：
Save the redacted version of /path/to/document.pdf5. list_loaded_pdfs
列出当前加载的所有PDF文件。
参数： 无
返回值： 已加载PDF文件的路径列表及页数
6. list_applied_redactions
列出已应用于加载的PDF文件中的所有编辑操作。 新工具 用于跟踪编辑进度并避免重复工作。
参数：
pdf_path(字符串，可选)：特定PDF文件的路径。如果未提供，则列出所有已加载PDF文件的遮蔽内容
返回值： 每个PDF中标记为需编辑的文本列表
示例：
# List redactions for a specific PDF
List applied redactions for /path/to/document.pdf
# List redactions for all loaded PDFs
List all applied redactions用例：
- 在添加更多遮蔽内容之前，请检查已遮蔽的部分
- 在多步骤过程中验证编辑进度
- 避免重复的编辑尝试
- 生成一份关于被删节内容的报告
7. close_pdf
关闭已加载的PDF文件并释放其资源。这也会清除该PDF的遮蔽跟踪记录。
参数：
pdf_path(字符串)：要关闭的PDF文件的路径
返回值： 确认信息
工作流示例
以下是使用此MCP服务器的典型工作流程：
- 加载一个PDF文件
Load the PDF at /Users/me/documents/sensitive.pdf- 审查内容
该工具将返回全文内容，您可以审阅以识别敏感信息。
- 编辑敏感文本（批处理模式 - 推荐）
Redact ["Social Security Number", "123-45-6789", "John Doe", "jane.smith@email.com"] in /Users/me/documents/sensitive.pdf专业小贴士： 一次性编辑多篇文本比多次调用工具要快得多。
- 检查已删除的内容（可选）
List applied redactions for /Users/me/documents/sensitive.pdf这显示了哪些文本已经被标记为需要编辑。
- 如有需要，请添加更多删节内容
Redact ["Additional Text", "Another Secret"] in /Users/me/documents/sensitive.pdf该工具将跳过步骤3中已进行遮蔽处理的任何文本。
- 编辑特定区域（可选）
Redact the area from (50, 100) to (200, 120) on page 2 of /Users/me/documents/sensitive.pdf- 保存已编辑过的PDF文件
Save the redacted version of /Users/me/documents/sensitive.pdf这将创建 /Users/me/documents/sensitive_redacted.pdf
- 关闭PDF文件（可选）
Close /Users/me/documents/sensitive.pdf技术细节
性能优化技巧
批量编辑速度更快：
# ❌ Slower: Multiple individual calls
Redact ["John Doe"] in document.pdf
Redact ["123-45-6789"] in document.pdf
Redact ["jane@email.com"] in document.pdf
# ✅ Faster: Single batch call
Redact ["John Doe", "123-45-6789", "jane@email.com"] in document.pdf为何批量编辑效果更佳：
- 减少工具调用开销
- 仅扫描一次PDF
- 一次性应用所有遮蔽操作
- 自动防止重复遮蔽
- 提供所有操作的单一汇总
最佳实践： 先收集所有文本进行编辑，然后再一次性调用（处理）。
依赖项
- FastMCP (>=2.12.0): 用于构建MCP服务器的Python框架
- PyMuPDF（注：这是一个专有名词，通常直接保留原样，但为了说明其含义，可以理解为“Python的MuPDF库”或“用于Python的MuPDF工具”，不过在实际应用中，直接使用“PyMuPDF”这一名称更为常见） (>=1.24.0): PDF 操作库（作为
fitz）
建筑学
- 内存存储加载的PDF文件保存在内存中，以便在编辑操作时快速访问
- 编辑追踪服务器会跟踪哪些文本已被编辑，以避免重复工作
- 批处理通过单次工具调用即可编辑多篇文本，以提高性能
- 惰性应用添加了编辑注释，但尚未应用，直到
save_redacted_pdf被称为 - 错误处理使用FastMCP的
ToolError以便向MCP客户端正确传播错误 - 上下文日志记录所有操作日志均记录在MCP上下文中，以确保透明度
（当前版本的）限制
- 仅文本编辑（或：纯文本编辑）此版本专注于文本编辑功能。图像编辑功能尚未实现。
- 内存使用情况加载时，PDF文件会保留在内存中。非常大的PDF文件可能会占用大量内存。
- 单次会话内存存储在服务器重启后不会持久保存。
发展
运行测试
# Install development dependencies
uv pip install -e ".[dev]"
# Run tests (when implemented)
pytest代码结构
redact_mcp/
├── src/
│ └── redact_mcp/
│ ├── __init__.py # Package initialization
│ └── server.py # Main MCP server implementation
├── pyproject.toml # Package configuration
└── README.md # This file许可证
Apache-2.0（Apache许可证第2版）
贡献；助力
欢迎贡献！请随时提交问题或拉取请求。