pdfmux: PDF extraction that checks itself
pdfmux
PDF extraction with self-checking: unreadable pages get a flag and never vanish silently, plus an MCP server for Claude
- 86 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The server reads your PDFs and writes results to disk
- When a cloud model is plugged in for fallback extraction, page text goes to the provider
Install
- Works in
Manual install
claude mcp add pdfmux -- npx -y pdfmux-mcpThe MCP server. Install the engine separately with `pip install pdfmux`.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The server reads your PDFs and writes results to disk
- When a cloud model is plugged in for fallback extraction, page text goes to the provider
This is third-party code. Review the repository files before installing.
What it does
pdfmux turns PDFs into Markdown, JSON or RAG chunks and checks the result itself. For each page it picks one of seven built-in extractors: PyMuPDF for digital text, RapidOCR for scans, Docling for tables, Marker for academic papers, Surya, OpenDataLoader and Mistral OCR. Blank pages, scrambled columns and broken tables are re-extracted with a stronger engine, and whatever still cannot be read is flagged. The `pdfmux verify` command also audits other tools' extractions, such as Docling, LlamaParse or Mistral OCR: it compares the output with the source PDF and shows which pages silently disappeared. For hard cases you plug in your own model by YAML: Gemini, Claude, GPT-4o, Ollama or Mistral, with your own keys. The `pdfmux-mcp` MCP server gives an agent the tools `convert_pdf`, `analyze_pdf`, `extract_structured`, `extract_streaming`, `get_pdf_metadata` and `batch_convert`, and a seventh tool verifies extraction.
Who it is for. Developers of RAG pipelines and anyone feeding agents PDFs with tables and scans who does not want silently lost pages.
Good fit when
- A directory of hundreds of PDFs includes scans, and blank pages hurt search
- Tables from a report must reach Markdown with their structure intact
- You compare a paid extractor with a free one and want to see which pages it lost
- An agent in Claude Desktop must read a PDF and return structured JSON
Not a fit when
- You only need plain text from a digital PDF: PyMuPDF alone is enough without self-checking
- The machine is short on space: extra engines weigh hundreds of megabytes, for example RapidOCR about 200 MB and Docling about 500 MB
- The document must not go to an external model: fallback extraction can call cloud models with your key
Example request
Extract the tables from the annual report to Markdown and tell me which pages pdfmux could not read.MCP
- Transport
- stdio
- Authentication
- not required
Limitations
The base install `pip install pdfmux` parses only digital PDFs. Scans need the `pdfmux[ocr]` extra, tables need `pdfmux[tables]` and complex layouts need `pdfmux[opendataloader]` with Java 11 or newer. Fallback model calls run on your own Gemini, Claude, GPT-4o, Ollama or Mistral key, and without one such pages stay flagged.
The author calls the decision method patent-pending. Some figures, such as 97.9 percent TEDS for Docling and 96.6 percent on tables for Mistral OCR, belong to other engines and are taken from the README. The MCP server needs Node.js while the engine itself is written in Python.
How to disable. Remove the server with `claude mcp remove pdfmux` and the package with `pip uninstall pdfmux`. Delete any YAML config holding your keys separately.
FAQ
How do I connect pdfmux to Claude Code?
Run `claude mcp add pdfmux -- npx -y pdfmux-mcp`. The engine itself is installed separately with `pip install pdfmux`.
How is pdfmux different from LlamaParse?
It is free, MIT licensed, runs locally and audits pages after extraction. The author calls it an open alternative to LlamaParse.
What does the pdfmux verify command do?
It compares any extractor's output with the source PDF and shows pages it silently dropped.
Do scans need OCR?
Yes, install `pip install "pdfmux[ocr]"`. Without it scanned pages return empty text. RapidOCR runs on CPU and takes about 200 MB.
Are there loaders for LangChain and LlamaIndex?
Yes, the README gives separate packages and examples, for example `llama-index-readers-pdfmux`.
Discussion
No questions or reviews yet.
Related
MCP serversMCP PDF for large documents: the agent searches by meaning and keyword across one file or a folder and reads only the pages, tables and scans it needs
MCP PDF from ComPDF: the agent converts PDFs and images to Word, Excel, Markdown and JSON and merges, splits, protects and compares files via a cloud API
An MCP server built on Docling: converts PDFs into structured documents, builds new ones and feeds them to RAG
An MCP server that turns PDF, DOCX, XLSX, PPTX, images, audio, web pages and YouTube transcripts into Markdown
Builds clickable bookmarks for a scanned PDF from its contents page and runs as an MCP server for Claude Desktop
Official MinerU MCP server: PDFs, Word, PowerPoint and images become Markdown with formulas and tables
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| pdfmux: PDF extraction that checks itself (this card) | no | not required | 86 | |
| MarkItDown | yes | not required | 195,183 | converts Microsoft Office formats to Markdown without page checks |
| Docling | no | 70,497 | one of the engines pdfmux uses for tables | |
| MinerU | no | 83,572 | a separate PDF parser without a self-check layer |
README in short
The README presents pdfmux as a pipeline: a router picks an extractor per page, an audit catches failures and re-extraction repairs them. It goes on to installation with extras, the `verify` certification mode, loaders for LangChain and LlamaIndex, the MCP server and plugging in your own model through YAML.