Benspdf

Ben's PDF tools for AI agents, exposed over the Model Context Protocol (MCP).

[!NOTE] Your PDFs are read on your own machine and never uploaded. With a hosted model your questions still reach that model; pair the tools with a local Ollama model and nothing leaves the machine at all.

Works with Claude Desktop, Claude Code, VS Code, Kiro, Cursor, the ChatGPT desktop app, and any other MCP client. The one-click buttons above need uv; for every other client, or to do it by hand, see Setup.

Tools

Every tool but one needs nothing beyond the package. pdf_ocr uses tesseract, a system program rather than a Python package, and only looks for it when you actually call it — so install it if and when you want OCR (brew install tesseract, sudo apt install tesseract-ocr, or winget install UB-Mannheim.TesseractOCR), and everything else works either way.

Where results go

When a tool makes a new PDF, it goes into a scratch folder instead of your own folders, and you get back a short id like art_a1b2c3d4.pdf. Tools accept those ids anywhere they accept a file path, so several steps can be chained together.

Results carry the artifact's path as well as its id, so you can open a rendered page or an intermediate file straight away without exporting it first.

export is the only tool that writes into your folders, so nothing shows up until you ask for it. Each time the server starts it clears out scratch files older than 7 days. Set BENSTOOLS_WORKSPACE to put the scratch folder somewhere other than ~/.benstools/work.

Setup

Install uv once, then point your client at uvx benspdf-mcp and uv fetches the package, plus a suitable Python, on first run.

# macOS and Linuxcurl -LsSf https://astral.sh/uv/install.sh | sh
# Windowspowershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

On macOS, brew install uv works too.

Add the server to your client with one of the configs below, then restart the server from your client's UI. Once connected, just ask in plain language:

How many pages are in ~/Downloads/report.pdf?

Claude Desktop

Edit claude_desktop_config.json, which lives at ~/Library/Application Support/Claude/ on macOS and %APPDATA%\Claude\ on Windows. You can also open it from Settings → Developer → Edit Config.

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

Claude Code

One command, no config file. Add --scope user to enable it everywhere rather than just the current project.

claude mcp add benspdf -- uvx benspdf-mcp

Check it connected with claude mcp list.

VS Code

.vscode/mcp.json in your workspace, or the same file in your user profile. Note VS Code uses servers rather than mcpServers, and wants an explicit type.

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

Kiro

.kiro/settings/mcp.json in your workspace, or ~/.kiro/settings/mcp.json to enable it everywhere. autoApprove skips the confirmation prompt for tools you trust.

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

Cursor

The button at the top does this for you. By hand, it's ~/.cursor/mcp.json to enable it everywhere, or .cursor/mcp.json in a project.

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

Windsurf

~/.codeium/windsurf/mcp_config.json. You can also reach it from Cascade: Settings → Cascade → Manage MCPs → View raw config, which is worth using since the path has moved between versions.

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

Continue

~/.continue/config.yaml, or a .yaml file under .continue/mcpServers/ in a project. Continue is the one client here that doesn't take the JSON shape above: its config is YAML, and mcpServers is a list rather than an object keyed by name.

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

ChatGPT desktop app, Codex CLI, Codex IDE extension

All three are Codex clients and share one config file, ~/.codex/config.toml, so adding the server once covers all of them. Note this one is TOML, not JSON.

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

Any other MCP client

Almost every client uses the same JSON as Claude Desktop above — an mcpServers object, with command set to uvx and args to ["benspdf-mcp"]. Some want an explicit "type": "stdio"; adding it is harmless where it isn't required.

If a client just asks for a command to run, it's:

uvx benspdf-mcp

Fully offline with Ollama

The clients above keep your PDFs local, but they answer using a hosted model. Pair the tools with a local model instead and nothing leaves your machine.

You'll need Ollama with a model pulled, plus this package:

pip install benspdf-mcp ollamaollama pull llama3.1

Then run the bundled CLI:

benspdf-cli                        # uses the first model you havebenspdf-cli --model llama3.1       # or pick oneBENSPDF_MODEL=llama3.1 benspdf-cli # or set it once

python -m benspdf.cli does the same thing, handy from a source checkout.

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.

Reference

Each tool's own description tells your client what it does and when to use it, so in normal use there is nothing to look up. If you want the detail — every field a tool returns, and the reasoning behind the answers it gives — see the tool reference.

To work on the code, see CONTRIBUTING.md.

License

Apache 2.0