{ "markdown": "\n\n
\n\n

BensPDF

\n\n

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

\n\n

\n\"PyPI\"\n\"Python\n\"License\"\n\"MCP\n

\n\n

Install in one click

\n\n

\n\"Install\n \n\"Install\n

\n\n
\n\n---\n\nBen's PDF tools for AI agents, exposed over the [Model Context Protocol](https://modelcontextprotocol.io) (MCP).\n\n> [!NOTE]\n> Your PDFs are read on your own machine and never uploaded. With a hosted model\n> your questions still reach that model; pair the tools with a local Ollama model\n> and nothing leaves the machine at all.\n\nWorks with Claude Desktop, Claude Code, VS Code, Kiro, Cursor, the ChatGPT\ndesktop app, and any other MCP client. The one-click buttons above need\n[uv](https://docs.astral.sh/uv/getting-started/installation/); for every other\nclient, or to do it by hand, see [Setup](#setup).\n\n## Tools\n\n| Tool | What it does |\n| --- | --- |\n| `pdf_page_count` | Counts the pages in a PDF |\n| `pdf_metadata` | Reads document properties: title, author, dates, producer |\n| `pdf_check_text` | Says whether a PDF is readable text or a scan that needs OCR |\n| `pdf_page_layout` | Page sizes, orientation, rotation and page boxes |\n| `pdf_check_access` | Encryption, and what the file permits: printing, copying, editing |\n| `pdf_render_pages` | Renders pages to images, so a page can be looked at |\n| `create_test_pdf_file` | Generates a throwaway PDF, handy for trying things out |\n| `export` | Saves results to a real location on disk |\n| `list_artifacts` | Lists recent temporary results |\n| `discard` | Deletes temporary results now |\n\n## Where results go\n\nWhen a tool makes a new PDF, it goes into a scratch folder instead of your own\nfolders, and you get back a short id like `art_a1b2c3d4.pdf`. Tools accept those\nids anywhere they accept a file path, so several steps can be chained together.\n\nResults carry the artifact's `path` as well as its id, so you can open a rendered\npage or an intermediate file straight away without exporting it first.\n\n`export` is the only tool that writes into your folders, so nothing shows up\nuntil you ask for it. Each time the server starts it clears out scratch files\nolder than 7 days. Set `BENSTOOLS_WORKSPACE` to put the scratch folder somewhere\nother than `~/.benstools/work`.\n\n## Setup\n\nInstall [uv](https://docs.astral.sh/uv/getting-started/installation/)\nonce, then point your client at `uvx benspdf-mcp` and uv fetches the package,\nplus a suitable Python, on first run.\n\n```bash\n# macOS and Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Windows\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\nOn macOS, `brew install uv` works too.\n\nAdd the server to your client with one of the configs below, then restart the\nserver from your client's UI. Once connected, just ask in plain language:\n\n> How many pages are in ~/Downloads/report.pdf?\n\n### Claude Desktop\n\nEdit `claude_desktop_config.json`, which lives at\n`~/Library/Application Support/Claude/` on macOS and `%APPDATA%\\Claude\\` on\nWindows. You can also open it from **Settings → Developer → Edit Config**.\n\n```json\n{\n \"mcpServers\": {\n \"benspdf\": {\n \"command\": \"uvx\",\n \"args\": [\"benspdf-mcp\"]\n }\n }\n}\n```\n\n### Claude Code\n\nOne command, no config file. Add `--scope user` to enable it everywhere rather\nthan just the current project.\n\n```bash\nclaude mcp add benspdf -- uvx benspdf-mcp\n```\n\nCheck it connected with `claude mcp list`.\n\n### VS Code\n\n`.vscode/mcp.json` in your workspace, or the same file in your user profile.\nNote VS Code uses `servers` rather than `mcpServers`, and wants an explicit\n`type`.\n\n```json\n{\n \"servers\": {\n \"benspdf\": {\n \"type\": \"stdio\",\n \"command\": \"uvx\",\n \"args\": [\"benspdf-mcp\"]\n }\n }\n}\n```\n\n### Kiro\n\n`.kiro/settings/mcp.json` in your workspace, or `~/.kiro/settings/mcp.json` to\nenable it everywhere. `autoApprove` skips the confirmation prompt for tools you\ntrust.\n\n```json\n{\n \"mcpServers\": {\n \"benspdf\": {\n \"command\": \"uvx\",\n \"args\": [\"benspdf-mcp\"],\n \"autoApprove\": [\"pdf_page_count\"]\n }\n }\n}\n```\n\n### Cursor\n\nThe button at the top does this for you. By hand, it's `~/.cursor/mcp.json` to\nenable it everywhere, or `.cursor/mcp.json` in a project.\n\n```json\n{\n \"mcpServers\": {\n \"benspdf\": {\n \"type\": \"stdio\",\n \"command\": \"uvx\",\n \"args\": [\"benspdf-mcp\"]\n }\n }\n}\n```\n\n### Windsurf\n\n`~/.codeium/windsurf/mcp_config.json`. You can also reach it from Cascade:\n**Settings → Cascade → Manage MCPs → View raw config**, which is worth using\nsince the path has moved between versions.\n\n```json\n{\n \"mcpServers\": {\n \"benspdf\": {\n \"command\": \"uvx\",\n \"args\": [\"benspdf-mcp\"]\n }\n }\n}\n```\n\n### Continue\n\n`~/.continue/config.yaml`, or a `.yaml` file under `.continue/mcpServers/` in a\nproject. Continue is the one client here that doesn't take the JSON shape above:\nits config is YAML, and `mcpServers` is a list rather than an object keyed by name.\n\n```yaml\nmcpServers:\n - name: benspdf\n command: uvx\n args:\n - benspdf-mcp\n```\n\n### ChatGPT desktop app, Codex CLI, Codex IDE extension\n\nAll three are Codex clients and share one config file, `~/.codex/config.toml`,\nso adding the server once covers all of them. Note this one is TOML, not JSON.\n\n```toml\n[mcp_servers.benspdf]\ncommand = \"uvx\"\nargs = [\"benspdf-mcp\"]\n```\n\n### Any other MCP client\n\nAlmost every client uses the same JSON as Claude Desktop above — an `mcpServers`\nobject, with `command` set to `uvx` and `args` to `[\"benspdf-mcp\"]`. Some want an\nexplicit `\"type\": \"stdio\"`; adding it is harmless where it isn't required.\n\nIf a client just asks for a command to run, it's:\n\n```\nuvx benspdf-mcp\n```\n\n## Fully offline with Ollama\n\nThe clients above keep your PDFs local, but they answer using a hosted model.\nPair the tools with a local model instead and nothing leaves your machine.\n\nYou'll need [Ollama](https://ollama.com) with a model pulled, plus this package:\n\n```bash\npip install benspdf-mcp ollama\nollama pull llama3.1\n```\n\nThen run the bundled CLI:\n\n```bash\nbenspdf-cli # uses the first model you have\nbenspdf-cli --model llama3.1 # or pick one\nBENSPDF_MODEL=llama3.1 benspdf-cli # or set it once\n```\n\n`python -m benspdf.cli` does the same thing, handy from a source checkout.\n\n```\nYou: how many pages in ~/Downloads/report.pdf?\n[Using tool: pdf_page_count]\n[Result: 12 pages in report.pdf]\nAssistant: The PDF has 12 pages.\n```\n\n## Reference\n\nEach tool's own description tells your client what it does and when to use it, so\nin normal use there is nothing to look up. If you want the detail — every field a\ntool returns, and the reasoning behind the answers it gives — see the\n[tool reference](https://github.com/benbergner/BensPDF/blob/main/docs/tools.md).\n\nTo work on the code, see\n[CONTRIBUTING.md](https://github.com/benbergner/BensPDF/blob/main/CONTRIBUTING.md).\n\n## License\n\nApache 2.0\n", "bytes": 8251, "sha": "8ff5d0e1897e486dca44ac704cde30a9c4c9893992e1d82390b8b987f5aa4da8", "repo_slug": "benbergner/benspdf", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_benbergner_benspdf_45fac365/readme" }