内容
# sam-pdf-studio-mcp
MCP（模型上下文协议）stdio 桥接，用于 **[Sam PDF Studio](https://github.com/wassermanproductions/sam-pdf-studio)** — 一个功能齐全的PDF编辑器。该服务器在无界面（headlessly）的情况下运行Sam PDF Studio的PyMuPDF引擎，因此任何MCP代理都可以直接在文件路径上合并、拆分、旋转、编辑、OCR、压缩、加密和转换PDF文件 — 无需GUI，无需窗口，无需点击。
零依赖。Node ≥ 18。一个文件。
## 它是什么
Sam PDF Studio附带一个自包含的Python引擎（`pdf_engine.py`），带有自己的虚拟环境。该桥接器是一个薄封装，它为每个工具调用启动该引擎作为子进程，并返回它打印的JSON。每个操作读取一个**输入**路径并写入一个新的**输出**路径 — 您的源文件永远不会在原地修改。
## 要求
1. **安装或构建Sam PDF Studio**，从 [Sam PDF Studio仓库](https://github.com/wassermanproductions/sam-pdf-studio) 。安装它会提供引擎虚拟环境（带有PyMuPDF、pypdf、pdf2docx、ocrmypdf和OCR/压缩二进制文件），该环境由此桥接器驱动。
2. 就是这样 — 无需配置。桥接器自动发现：
- 引擎Python在 `~/Library/Application Support/SamPDFStudio/engine-venv/bin/python3`，
- 引擎脚本 `pdf_engine.py` 在已安装的应用（或本地构建）内。
如果您的安装位于其他位置，请使用 `SAMPDF_ENGINE_PYTHON` 和 `SAMPDF_ENGINE_SCRIPT` 环境变量覆盖它们。运行 `health` 工具首先确认引擎和所有依赖项都存在。
## 连接
### Hermes
添加到 `~/.hermes/config.yaml` （或从Hermes MCP目录安装后）:
```yaml
mcp_servers:
sam-pdf-studio:
command: "node"
args: ["/absolute/path/to/sam-pdf-studio-mcp/sam-pdf-studio-mcp.mjs"]
```
### Claude Code
```bash
claude mcp add sam-pdf-studio -- node /absolute/path/to/sam-pdf-studio-mcp/sam-pdf-studio-mcp.mjs
```
### Codex
添加到 `~/.codex/config.toml`:
```toml
[mcp_servers.sam-pdf-studio]
command = "node"
args = ["/absolute/path/to/sam-pdf-studio-mcp/sam-pdf-studio-mcp.mjs"]
```
### 任意MCP客户端（通用stdio配置）
```json
{ "mcpServers": { "sam-pdf-studio": { "command": "node", "args": ["/absolute/path/to/sam-pdf-studio-mcp/sam-pdf-studio-mcp.mjs"] } } }
```
## 工具（23）
首先调用 `health` 以确认引擎已准备就绪。每个工具都接受一个绝对的 `input` 路径，并写入一个新的 `output` 路径（或 `output_dir`）；坐标以PDF点为单位，页码从1开始。
| 工具 | 功能 |
| --- | --- |
| `health` | 验证引擎和所有依赖项是否已安装。 |
| `metadata` | 读取页数和文档元数据。 |
| `merge_pdfs` | 将多个PDF合并为一个。 |
| `split_pdf` | 将PDF拆分为每页一个文件的目录。 |
| `extract_pages` | 仅保留所选页面。 |
| `delete_pages` | 删除所选页面。 |
| `rotate_pages` | 将页面旋转90/180/270°。 |
| `replace_text` | 查找并替换字面文本，匹配样式。 |
| `redact_text` | 永久遮盖并删除文本。 |
| `add_text` | 在页面上绘制文本。 |
| `add_image` | 在页面上放置图像。 |
| `add_link` | 添加可点击的URL超链接。 |
| `compress_pdf` | 减小文件大小。 |
| `add_page_numbers` | 盖章页码。 |
| `resize_pages` | 将页面缩放为新大小。 |
| `set_password` | 用打开密码加密。 |
| `ocr` | 为扫描件添加可搜索的文本层。 |
| `export_docx` | 转换为可编辑的Word `.docx`。 |
| `export_xlsx` | 将表格提取到Excel `.xlsx`。 |
| `export_pptx` | 将页面转换为PowerPoint幻灯片。 |
| `export_text` | 将文本提取到 `.txt` / Markdown / HTML。 |
| `export_images` | 将页面渲染为PNG/JPG。 |
| `images_to_pdf` | 将图像合并为PDF。 |
## 安全
此桥接器**仅**在您指向的**本地文件**上运行经过审查的Sam PDF Studio引擎。它不打开网络连接，不绑定端口，也不传递凭证。它启动从Sam PDF Studio安装（或您的显式 `SAMPDF_ENGINE_*` 覆盖）解析的引擎Python，除此之外不执行任何操作。输出始终写入新路径，因此输入永远不会被修改。
## 支持
少数人询问是否可以发送小费以支持我开发开源工具。所以我设置了一个可选的方式，以防有人愿意这样做。
完全没有压力。使用应用程序、分享它们、在仓库上加星和贡献代码也同样有帮助。谢谢。
- [GitHub赞助](https://github.com/sponsors/wassermanproductions)
- [Ko-fi](https://ko-fi.com/samwasserman)
## 许可证和致谢
Apache-2.0 — 见 [LICENSE](LICENSE)。根据 [NOTICE](NOTICE) 文件，使用、分支和重新分发必须注明 **Sam Wasserman ([wassermanproductions.com](https://wassermanproductions.com))** 。
