BensPDF

PDF tools for AI agents. Your files never leave your machine.

Install in one click

--- Ben's PDF tools for AI agents, exposed over the [Model Context Protocol](https://modelcontextprotocol.io) (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](https://docs.astral.sh/uv/getting-started/installation/); for every other client, or to do it by hand, see [Setup](#setup). ## Tools | Tool | What it does | | --- | --- | | `pdf_page_count` | Counts the pages in a PDF | | `pdf_metadata` | Reads document properties: title, author, dates, producer | | `pdf_check_text` | Says whether a PDF is readable text or a scan that needs OCR | | `pdf_extract_text` | Reads the text a PDF holds, page by page | | `pdf_page_layout` | Page sizes, orientation, rotation and page boxes | | `pdf_check_access` | Encryption, and what the file permits: printing, copying, editing | | `pdf_render_pages` | Renders pages to images, so a page can be looked at | | `pdf_ocr` | Reads a scan with OCR, and can add a searchable text layer to it | | `create_test_pdf_file` | Generates a throwaway PDF, handy for trying things out | | `export` | Saves results to a real location on disk | | `list_artifacts` | Lists recent temporary results | | `discard` | Deletes temporary results now | Every tool but one needs nothing beyond the package. `pdf_ocr` uses [tesseract](https://github.com/tesseract-ocr/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](https://docs.astral.sh/uv/getting-started/installation/) once, then point your client at `uvx benspdf-mcp` and uv fetches the package, plus a suitable Python, on first run. ```bash # 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" ``` 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**. ```json { "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. ```bash 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`. ```json { "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. ```json { "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. ```json { "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. ```json { "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. ```yaml 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. ```toml [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](https://ollama.com) with a model pulled, plus this package: ```bash pip install benspdf-mcp ollama ollama pull llama3.1 ``` Then run the bundled CLI: ```bash 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` 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](https://github.com/benbergner/BensPDF/blob/main/docs/tools.md). To work on the code, see [CONTRIBUTING.md](https://github.com/benbergner/BensPDF/blob/main/CONTRIBUTING.md). ## License Apache 2.0