pdf-toolkit-mcp

Everyday PDF tasks for your AI agent, with nothing to install but Python.

pdf-toolkit-mcp is an MCP server that lets an agent look inside a PDF, read it in budget-sized pieces, search it, pull out tables and images, and merge, split, reorder or rotate pages. It is built on pure-Python wheels only (pypdf and pdfplumber), so uvx pdf-toolkit-mcp works the same on Windows, macOS and Linux: no Java, no Ghostscript, no Poppler, no Camelot, no compiler.

What it looks like

> pdf_info report.pdf
Pages: 312
Encrypted: no
Text layer: yes (10/10 sampled pages have extractable text)
Page sizes (points, 72 per inch):
  595 x 842 (A4): pages 1-311
  842 x 595 (A4 landscape): pages 312
Outline / bookmarks:
  - Introduction (page 3)
  - Results (page 41)
    - Revenue by region (page 44)

> read_pdf report.pdf pages="41-"
--- Page 41 of 312 ---
...
[Output truncated at about 8000 tokens. Continue with pages="47-312" (266 more page(s), starting at page 47).]

> search_pdf report.pdf query="net revenue"
14 match(es) on 6 page(s) (44-46,88,201-202):
Page 44: ...Q3 net revenue rose 12% to 4.1M, driven by...

> read_pdf scan.pdf
WARNING: none of the selected pages has a text layer. This PDF looks scanned (images
only); extracting text needs OCR, which this server does not do.

Related MCP server: benspdf

Install

You need uv (or pip install pdf-toolkit-mcp).

Claude Code

claude mcp add pdf -- uvx pdf-toolkit-mcp --dir ~/Documents --dir ~/Downloads

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "pdf": {
      "command": "uvx",
      "args": ["pdf-toolkit-mcp", "--dir", "C:\\Users\\you\\Documents", "--dir", "C:\\Users\\you\\Downloads"]
    }
  }
}

The server can only touch the folders you pass with --dir (repeat the flag for more). With no --dir it uses the folder it was started in, which for Claude Desktop is rarely where your PDFs are, so pass at least one.

Tools

Page ranges are 1-based: 1-3,5,7- (7- means page 7 to the end).

Try asking

• "What is in ~/Downloads/contract.pdf? How many pages, and does it have bookmarks?"

• "Find every mention of 'termination' in the contract and tell me which pages."

• "Read pages 12 to 15 of the annual report and summarise the revenue section."

• "Pull the tables from pages 30-35 of statement.pdf as CSV."

• "Split book.pdf into chapters: 1-24, 25-60 and 61 to the end."

• "Merge cover.pdf, body.pdf and appendix.pdf into final.pdf."

• "Page 4 of scan-001.pdf is sideways. Rotate it and save a fixed copy."

• "Pull all the photos out of brochure.pdf."

• "This PDF is password protected, the password is ... Read the first page."

Safety

• Folder allow-list. Every read and every write must resolve inside a --dir folder. .. tricks, symlinks that point outside and sibling folders with a similar name are all rejected.

• No silent overwrites. Write tools refuse to replace an existing file unless the call passes overwrite=true. split_pdf checks every output name before writing any, and overwrites go through a temporary file so a failure cannot leave a half-written PDF.

• Originals are never modified unless you point output_path at the input and set overwrite=true yourself.

• Passwords are a call parameter. They are handed to the PDF library and nowhere else: never logged, stored, or included in an error message. Output PDFs are not encrypted.

• Errors are explicit and say what to do next (wrong password, page out of range, file exists, path outside the allowed folders). Nothing falls back silently.

Limits

• No OCR. A scanned PDF has no text to extract. The tools detect this and say so rather than return an empty string; use an OCR tool on the page images (extract_images can export them).

• Text extraction follows the PDF's own text layer. Multi-column pages can interleave; layout=true often helps.

• Table detection is heuristic. Ruled tables are reliable; borderless ones need strategy="text" and may need checking.

• Encrypted outputs, form filling, annotations and redaction are out of scope.

Learn how it is built

pdf-mcp-the-hard-way is a seven-module tutorial that builds a minimal version of this server from the raw bytes of a PDF up.

Tests

uv sync --extra test
uv run pytest tests

The tests generate real PDFs with reportlab (multi-page, Turkish text, ruled and borderless tables, bookmarks, AES-256 encryption, image-only scans, a 300-page document), run every tool against them, and drive the installed server over a real MCP stdio session.

License

MIT