PDF处理服务

MuPDF MCP服务器

MCP（模型上下文协议）服务器，使用 在PDF 通过 mupdf-rs.

建筑

此服务器提供 两种使用模式:

STATEFUL API（用于多个操作）

1. import_document → 接收a document_id
2. 使用执行操作 document_id
3. close_document 完成后
4. 在以下情况下使用： 您需要对同一文档执行多个操作

ONESHOT API（用于单次操作）

1. 呼叫 oneshot_* 直接使用文件路径或base64的工具
2. 立即获得结果，无需清理
3. 在以下情况下使用： 您只需对文档进行一次操作

安装

使用Docker（推荐）

# Build release binary
docker compose run --rm build-release

# The binary will be at target/release/mupdf-mcp-server

本地构建

需要：Rust nightly、libclang、freetype、harfbuzz、libjpeg、openjp2、zlib

cargo build --release

发展

运行测试

# Run tests via Docker (recommended)
docker compose run --rm test

# Run tests natively (requires dependencies installed)
cargo test

测试覆盖率

# Generate HTML coverage report (output in target/llvm-cov/html/)
docker compose run --rm coverage

# Generate LCOV report (for CI/Codecov)
docker compose run --rm coverage-lcov

测试夹具

测试PDF文件位于 tests/fixtures/ 来源于 mupdf-rs.

用法

使用克劳德桌面

添加到您的Claude Desktop配置(claude_desktop_config.json):

{
  "mcpServers": {
    "mupdf": {
      "command": "/path/to/mupdf-mcp-server"
    }
  }
}

独立

./target/release/mupdf-mcp-server

服务器使用MCP协议通过STDIO进行通信。

功能检查表

法定API

会话管理

• [x] import_document -导入文档（文件路径或base64）→ 返回document_id
• [x] close_document -关闭文档并释放内存
• [x] list_documents -列出打开的文档

文档操作（需要Document_id）

• [x] get_metadata -获取文档元数据（标题、作者、主题、关键字、创建者、生产者、创建日期、修改日期）
• [x] get_page_count -获取总页数
• [x] get_outlines -获取包含页码的目录/书签
• [x] needs_password -检查是否需要密码
• [ ] authenticate -使用密码解锁文档
• [x] is_pdf -检查文档是否为PDF格式
• [x] is_reflowable -检查文档是否可回流（例如EPUB）
• [x] resolve_link -解析指向目标页面的链接URI

页面操作（需要document_id+Page_number）

• [x] get_page_bounds -获取页面尺寸（宽度、高度）
• [x] get_page_links -在页面上获取带有边界和URI的超链接
• [x] search_page -在页面上查找文本，返回匹配坐标
• [x] get_page_text -提取各种格式的文本（纯文本、html、json、xml）
• [x] get_page_text_blocks -获取具有定位功能的结构化文本块
• [x] render_page -将页面渲染为PNG（base64编码）

PDF修改（需要document_id）

• [ ] create_blank_pdf -创建新的空PDF→ 返回document_id
• [ ] add_page -在指定位置添加新的空白页
• [ ] delete_page -在指定位置删除页面
• [ ] set_page_rotation -设置页面旋转（0、90、180、270）
• [ ] set_outlines -设置/更新书签
• [ ] save_document -将文档保存到文件路径
• [ ] export_document -将文档导出为base64

ONESHOT API（不需要document_id）

• [x] oneshot_get_bookmarks -提取所有书签及其目标页码

api参考

会话管理

import_document

将文档导入服务器。

参数：

• source：对象具有以下任一属性：
  • path：String-PDF的文件路径
  • base64：字符串-Base64编码的PDF内容
  • filename：String（可选）-base64内容的文件名提示
• password：字符串（可选）-加密PDF的密码

退货：

• document_id：String-引用此文档的UUID

close_document

关闭文档并释放其内存。

参数：

• document_id：String-来自import_Document的文档ID

list_documents

列出所有打开的文档。

退货：

• documents：对象数组，包含：
  • document_id：字符串
  • page_count：编号
  • created_at：字符串（ISO时间戳）

文档操作

get_page_count

获取总页数。

参数：

• document_id：字符串

退货：

• page_count：编号

get_metadata

获取文档元数据。

参数：

• document_id：字符串

退货：

• title：字符串或null
• author：字符串或null
• subject：字符串或null
• keywords：字符串或null
• creator：字符串或null
• producer：字符串或null
• creation_date：字符串或null
• modification_date：字符串或null

get_outlines

获取目录/书签。

参数：

• document_id：字符串

退货：

• outlines：大纲条目数组（递归结构）
  • title：字符串
  • page：编号（0索引）
  • children：大纲条目数组

页面操作

get_page_text

从页面中提取文本。

参数：

• document_id：字符串
• page：编号（0索引）
• format：String（可选）-“plain”（默认）、“html”、“json”、“xml”

退货：

• text：String-以请求格式提取的文本

render_page

将页面渲染为图像。

参数：

• document_id：字符串
• page：编号（0索引）
• scale：数字（可选，默认值1.0）
• format：字符串（可选）-“png”（默认）或“svg”

退货：

• image：String-Base64编码的图像数据
• width：编号
• height：编号
• format：字符串

ONESHOT工具

oneshot_get_bookmarks

提取带有页码的书签。不需要document_id。

参数：

• source：对象具有以下任一属性：
  • path：String-PDF的文件路径
  • base64：字符串-Base64编码的PDF内容
• password：字符串（可选）

退货：

• bookmarks：书签条目数组
  • title：字符串
  • page：编号（0索引）
  • level：编号（嵌套深度，0=顶层）
• page_count：编号

许可证

AGPL-3.0（由于MuPDF许可）

学分

• 在PDF -基础PDF库
• mupdf-rs -MuPDF的Rust绑定
• rmcp -Rust MCP SDK