About pdffr
pdffr-mcp is a local MCP server that converts PDFs into Markdown for agents and other MCP clients. It reads glyph geometry first and applies on-device OCR only to unexplained page content, keeping documents on the machine.
Key features
- 01PDF-to-Markdown conversion
- 02Geometry-based text extraction
- 03On-device OCR for unexplained content
- 04PDF heading outlines
- 05Tables returned as JSON
Use cases
- 01Extract text from born-digital PDFs
- 02Read scanned pages using OCR
- 03Inspect document headings before selecting pages
- 04Retrieve PDF tables for structured processing
MCP support
Exposes PDF conversion, outline and table tools to MCP clients. Inputs can be provided as a file path, URL or base64 data.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
Tools
3Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| ocr | boolean | No | Escalate ink the text layer cannot explain to on-device OCR (default true) |
| url | string | No | URL of a PDF to fetch |
| lang | string | No | Tesseract language(s) for OCR, e.g. 'eng', 'deu', 'eng+ara' (default 'eng') |
| path | string | No | Path to a PDF on this machine |
| pages | string | No | Page selection like '1-3,7' (default all) |
| base64 | string | No | Raw PDF bytes, base64-encoded |
| maxChars | integer | No | Truncate the Markdown to this many characters (default 200000) |
Details
From the project READMEpdffr-mcp
An MCP server that gives any agent — Claude Desktop, Claude Code, Cursor, Windsurf, Zed, your own — a local, private PDF → Markdown tool backed by pdffr. Born-digital pages decompile from glyph geometry in milliseconds; scans and screenshots get on-device OCR only where the text layer can't explain the ink. Nothing leaves the machine.
Install
Claude Desktop / Claude Code / Cursor / Windsurf — add to your MCP config:
{
"mcpServers": {
"pdffr": {
"command": "npx",
"args": ["-y", "pdffr-mcp"]
}
}
}
Claude Code one-liner:
claude mcp add pdffr -- npx -y pdffr-mcp
Requires Node 20+. The first run downloads the OCR model for the requested language (English by default) into the OS temp directory.
Tools
pdf_to_markdown
Decompile a PDF to Markdown. Give it one of path, url or base64.
| Argument | Type | Notes |
|---|---|---|
path | string | absolute or relative file path |
url | string | fetched with the server's network access |
base64 | string | raw PDF bytes |
pages | string | e.g. "1-3,7"; default all |
ocr | boolean | escalate unexplained ink to OCR (default true) |
lang | string | tesseract language(s), e.g. "deu", "eng+ara" (default "eng") |
maxChars | number | truncate the result (default 200 000) — the response says if it did |
Returns the Markdown, followed by a one-line stats footer (pages, time, OCR regions).
pdf_outline
Headings only — level, text and page — so an agent can decide which pages to read before paying for them. Same inputs (path / url / base64, ocr, lang).
pdf_tables
Every table as JSON rows ([{ page, rows: string[][] }]). Same inputs.
Why not a vision model
A PDF already knows where every glyph is. pdffr reads that geometry directly and reserves OCR for the pixels the text layer doesn't explain, so a 30-page report comes back in well under a second and a scanned invoice in a couple of seconds — with no API key and no upload. See the architecture notes.
MIT © Amer Sarhan
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.