pdf-parser-mcp

# pdf-parser-mcp MCP server that parses PDFs for LLM workflows. It extracts text with LiteParse, identifies likely figure pages with a deterministic spatial heuristic, and renders screenshots so the client can inspect visual pages directly. **Fast local parsing. No GPU. No API keys. The default pipeline does not run OCR or model inference.** ## Install ```bash claude mcp add pdf-parser -- npx -y pdf-parser-mcp ``` That's it. Restart Claude Code and the `parse_pdf` tool is available. ### Prerequisites [LiteParse](https://github.com/run-llama/liteparse) must be installed globally (Node.js ≥20 required): ```bash npm i -g @llamaindex/liteparse ``` macOS users can alternatively install via Homebrew: ```bash brew install run-llama/liteparse/llamaindex-liteparse ``` ## What it does When you ask Claude Code to read a PDF, the server: 1. **Extracts all text** using LiteParse — preserves whitespace-aligned tables and captures chart labels, legends, and annotations from the PDF text layer when present 2. **Detects likely figure pages** using spatial heuristics — uses text item distribution, numeric density, and font diversity to separate figure-heavy pages from dense prose 3. **Renders screenshots** of detected figure pages at 108 DPI — so the LLM can inspect charts visually instead of relying on axis labels alone The agent receives full-document text plus images for likely visual pages. Text-only pages do not consume vision tokens. ## Tools ### `parse_pdf` Parse a PDF and get text + figure page screenshots. ``` Input: pdf_path (string), cache_dir (string, optional) Output: text_path, figure_pages, figure_image_paths, page_count ``` The agent reads `text_path` for full document content and each `figure_image_path` to view charts/figures. ### `get_page_image` Render any page on demand (for pages not auto-detected as figures). ``` Input: pdf_path (string), page_no (number), cache_dir (string, optional) Output: image_path ``` ### `search_cache` Search previously parsed PDFs by filename or title. ``` Input: query (string), cache_dir (string, optional) Output: matching documents with metadata ``` ## How figure detection works The spatial heuristic classifies pages without any ML model. It uses five signals from LiteParse's bounding box data: | Signal | Figure indicator | Text indicator | |---|---|---| | Numeric item ratio | >5% (axis labels, data values) | <5% | | Font size diversity | ≥5 different sizes (title, axis, legend, labels) | ≤3 sizes | | Spatial scatter | High (items distributed across page) | Low (items flow in columns) | | Numeric item count | ≥10 | <5 | | Text density | Low (sparse layout with whitespace) | High (dense prose) | Three penalties reduce false positives: - **Data tables**: high numeric ratio + uniform fonts = table, not chart - **Uniform documents**: low font diversity + moderate density = spec text - **Cover pages**: very few items + high scatter = title slide The thresholds were tuned on a small internal set of 5 PDFs (135 pages total): presentation, academic paper, industry report, financial report, and technical spec. Treat them as practical defaults rather than a general benchmark. ## Benchmarks On the documents tested while building the tool, end-to-end parse time was generally on the order of seconds rather than tens of seconds. Exact throughput depends on document length, PDF structure, LiteParse version, machine, and whether the result is already cached. Figure-page screenshots increase vision-token usage. The tradeoff is deliberate: the server sends images only for pages that look visually dense enough to benefit from inspection. ## Configuration Default screenshot DPI is 108. In local testing, 72 DPI made chart labels harder to read, while 150 DPI increased image size without a clear gain on the tested documents. Results are cached to disk by content hash. Repeated parses of the same PDF can return quickly from cache. ## License MIT