PDF Toolbox

Expose local PDFs to MCP-compatible agents or run the standalone pdf-reader CLI with deterministic chunking, semantic search, and configurable defaults.

Highlights

• FastMCP/STDIO server ready for Cursor, VS Code, Claude, and other MCP clients.
• Typer/Click/Rich CLI (pdf-reader) prints JSON for easy piping.
• read_pdf – extracts ordered text with page-window controls for quick inspection.
• search_pdf – runs semantic similarity search over cached embeddings with custom top_k, score threshold, and chunk parameters.
• describe_pdf_sections – emits deterministic chunks for classic RAG flows or, with --mode tables, returns structured tables (bbox, headers, cells) detected straight from the pages.
• configure_pdf_defaults – adjusts chunk size/overlap, page windows, and the default embedding model at runtime.
• Strict .pdf validation, sandboxed base path, and aggressive caching.

Documentation

• Getting started
• CLI reference
• MCP integration
• Advanced options

Quick install (uv)

Run the MCP server directly

# Run the MCP server directly
uvx --from git+https://github.com/patriciomartinns/pdf-toolbox -- pdf-toolbox --quiet

# Install/run the CLI
uv tool install --from git+https://github.com/patriciomartinns/pdf-toolbox pdf-reader
pdf-reader --help

Note: If you had the old mcp-pdf-reader CLI installed via uv tool install, run uv tool uninstall mcp-pdf-reader before installing pdf-reader to avoid conflicts.

CLI quick tour

Tip: the first search-pdf invocation on a new document downloads the SentenceTransformers model and builds embeddings, so it can take longer once per model/PDF combo. Subsequent searches reuse the cache.

See the docs/ folder for full recipes covering both CLI commands and MCP client configuration. Questions or ideas? Open an issue on github.com/patriciomartinns/pdf-toolbox.