benspdf

---

Ben 为 AI Agent 打造的 PDF 工具，通过 Model Context Protocol（MCP）提供。

说明

你的 PDF 在自己的设备上读取，绝不会上传。使用托管模型时，你的问题仍会发送给该模型；搭配本地 Ollama 模型使用这些工具，则数据完全不会离开设备。

支持 Claude Desktop、Claude Code、VS Code、Kiro、Cursor、ChatGPT 桌面应用，以及其他任何 MCP 客户端。上方的一键安装按钮需要 uv；其他客户端的配置方法，或手动配置方法，请参阅设置。

工具

工具	功能
pdf_page_count	统计 PDF 页数
pdf_metadata	读取文档属性：标题、作者、日期、生成程序
pdf_check_text	检查 PDF 是否包含可读取的文本，还是需要 OCR 的扫描件
pdf_extract_text	逐页读取 PDF 中的文本
pdf_page_layout	查看页面尺寸、方向、旋转角度和页面框
pdf_check_access	检查加密情况，以及文件允许的操作：打印、复制、编辑
pdf_render_pages	将页面渲染为图像，以便查看
pdf_ocr	使用 OCR 读取扫描件，并可为其添加可搜索的文本层
create_test_pdf_file	生成临时 PDF，方便试用
export	将结果保存到磁盘上的实际位置
list_artifacts	列出近期的临时结果
discard	立即删除临时结果

除了一个工具外，其他工具都不需要额外安装任何东西。pdf_ocr 使用 tesseract，这是一个系统程序，而不是 Python 软件包；只有在实际调用它时才会查找它。因此，想使用 OCR 时再安装即可（brew install tesseract、sudo apt install tesseract-ocr 或 winget install UB-Mannheim.TesseractOCR），无论是否安装，其他功能都能正常使用。

结果存放位置

工具生成新的 PDF 时，会将其放入临时文件夹，而不是你自己的文件夹，并返回一个简短 ID，例如 art_a1b2c3d4.pdf。只要工具接受文件路径，就可以使用这些 ID，因此可以将多个步骤串联起来。

结果中除了 ID，还会包含工件的 path，因此无需先导出，就能直接打开渲染后的页面或中间文件。

只有 export 工具会将文件写入你的文件夹，因此在你提出请求之前，不会有任何内容显示出来。每次服务启动时，都会清除超过 7 天的临时文件。设置 BENSTOOLS_WORKSPACE，即可将临时文件夹放在 ~/.benstools/work 以外的位置。

设置

只需安装一次 uv，然后让客户端使用 uvx benspdf-mcp。首次运行时，uv 会获取该软件包以及合适的 Python 版本。

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

在 macOS 上，也可以使用 brew install uv。

使用以下任一配置将服务添加到客户端，然后在客户端的界面中重启服务。连接成功后，只需用自然语言提问：

~/Downloads/report.pdf 有多少页？

Claude Desktop

编辑 claude_desktop_config.json。在 macOS 上，该文件位于 ~/Library/Application Support/Claude/；在 Windows 上，位于 %APPDATA%\Claude\。你也可以通过 Settings → Developer → Edit Config 打开该文件。

{
  "mcpServers": {
    "benspdf": {
      "command": "uvx",
      "args": ["benspdf-mcp"]
    }
  }
}

Claude Code

只需一条命令，无需配置文件。添加 --scope user，即可在所有项目中启用，而不仅限于当前项目。

claude mcp add benspdf -- uvx benspdf-mcp

使用 claude mcp list 检查是否已连接。

VS Code

在工作区中使用 .vscode/mcp.json，或在用户配置文件中使用同名文件。请注意，VS Code 使用 servers 而不是 mcpServers，并且要求显式指定 type。

{
  "servers": {
    "benspdf": {
      "type": "stdio",
      "command": "uvx",
      "args": ["benspdf-mcp"]
    }
  }
}

Kiro

在工作区中使用 .kiro/settings/mcp.json，或使用 ~/.kiro/settings/mcp.json 在所有项目中启用。autoApprove 会跳过对你信任的工具的确认提示。

{
  "mcpServers": {
    "benspdf": {
      "command": "uvx",
      "args": ["benspdf-mcp"],
      "autoApprove": ["pdf_page_count"]
    }
  }
}

Cursor

顶部的按钮会为你完成这些操作。手动配置时，使用 ~/.cursor/mcp.json 可在所有项目中启用，或在项目中使用 .cursor/mcp.json。

{
  "mcpServers": {
    "benspdf": {
      "type": "stdio",
      "command": "uvx",
      "args": ["benspdf-mcp"]
    }
  }
}

Windsurf

使用 ~/.codeium/windsurf/mcp_config.json。你也可以通过 Cascade 打开该文件：Settings → Cascade → Manage MCPs → View raw config。由于文件路径在不同版本间有所变动，建议使用此方式。

{
  "mcpServers": {
    "benspdf": {
      "command": "uvx",
      "args": ["benspdf-mcp"]
    }
  }
}

Continue

使用 ~/.continue/config.yaml，或在项目的 .continue/mcpServers/ 下使用 .yaml 文件。Continue 是这里唯一不使用上述 JSON 格式的客户端：它的配置采用 YAML，且 mcpServers 是列表，而不是以名称为键的对象。

mcpServers:
  - name: benspdf
    command: uvx
    args:
      - benspdf-mcp

ChatGPT 桌面应用、Codex CLI、Codex IDE 扩展

这三者都是 Codex 客户端，共用一个配置文件 ~/.codex/config.toml，因此添加一次服务即可供它们全部使用。请注意，该配置文件使用 TOML，而不是 JSON。

[mcp_servers.benspdf]
command = "uvx"
args = ["benspdf-mcp"]

其他 MCP 客户端

几乎所有客户端都使用与上文 Claude Desktop 相同的 JSON 格式——一个 mcpServers 对象，其中 command 设为 uvx，args 设为 ["benspdf-mcp"]。有些客户端要求显式指定 "type": "stdio"；对于不要求此项的客户端，添加它也不会有问题。

如果客户端只要求输入要运行的命令，请使用：

uvx benspdf-mcp

使用 Ollama 完全离线运行

上文的客户端会让你的 PDF 保留在本地，但回答问题时会使用托管模型。改用本地模型搭配这些工具，即可确保所有数据都不会离开你的设备。

你需要安装 Ollama 并拉取一个模型，还需要安装此软件包：

pip install benspdf-mcp ollama
ollama pull llama3.1

然后运行捆绑的 CLI：

benspdf-cli                        # uses the first model you have
benspdf-cli --model llama3.1       # or pick one
BENSPDF_MODEL=llama3.1 benspdf-cli # or set it once

python -m benspdf.cli 的作用相同，也可以在源码检出目录中运行。

You: how many pages in ~/Downloads/report.pdf?
[Using tool: pdf_page_count]
[Result: 12 pages in report.pdf]
Assistant: The PDF has 12 pages.

参考

每个工具的说明都会告诉客户端它的用途和适用场景，因此通常无需查阅其他资料。如果你想了解详情——工具返回的每个字段，以及它给出答案背后的推理——请参阅工具参考。

如需参与代码开发，请参阅 CONTRIBUTING.md。

许可证

Apache 2.0