PDFMux MCP Server: Intelligent PDF Extraction Inside Claude, Cursor, and Windsurf

Direct answer: PDFMux ships an MCP (Model Context Protocol) server that lets Claude Desktop, Cursor, Windsurf, and VS Code Copilot read PDFs with confidence scoring, multi-method extraction (PyMuPDF, OCR, and LLM fallback), and structured output. Install with npx -y pdfmux. It exposes four tools (convert_pdf, analyze_pdf, extract_structured, batch_convert), is published to Smithery, PulseMCP, mcp.so, Glama, and the official MCP registry, and is the only PDF MCP server that tells the model when extraction failed instead of returning silent garbage.

Why most PDF MCP servers are not enough

There are now more than ten PDF MCP servers on the public registries. Almost all of them wrap a single extractor: pdf-parse in Node, or basic PyMuPDF text extraction in Python. They return a string. No confidence signal. No fallback when the page is scanned. No structured output for tables.

That works on a clean digital PDF. It breaks on the documents people actually need their agents to read: scanned contracts, bilingual invoices, financial reports with nested tables, mixed-method documents with some digital pages and some photographed ones. The extractor returns partial text and the agent cheerfully hallucinates the rest.

PDFMux takes a different approach. Each page goes through a routed pipeline (PyMuPDF first, quality audit, selective OCR on failures, LLM fallback for unrecoverable pages) with a confidence score attached to every result. When the extraction is not good enough, the MCP response says so. The agent then knows to ask the user for a better scan, fall back to a different tool, or refuse to answer rather than inventing a number.

PDFMux scores 0.900 on opendataloader-bench (benchmark #2 globally) and is the only MCP server surfacing that quality signal to the model. See the full benchmark of every PDF to Markdown tool for context.

Install in 30 seconds

The PDFMux MCP server runs via npx. You do not need Python, Docker, or a local clone.

npx -y pdfmux

That one command:

1. Pulls the npm wrapper.
2. Bootstraps a Python virtualenv on first run.
3. Installs pdfmux[serve] with all extraction dependencies.
4. Starts the MCP server on stdio.

Subsequent runs are cached. Cold start is about 8 seconds the first time, under 200 ms after that.

Claude Desktop config

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "pdfmux": {
      "command": "npx",
      "args": ["-y", "pdfmux"]
    }
  }
}

Restart Claude Desktop. The four PDFMux tools appear in the tool picker.

Cursor config

Cursor reads ~/.cursor/mcp.json:

{
  "mcpServers": {
    "pdfmux": {
      "command": "npx",
      "args": ["-y", "pdfmux"]
    }
  }
}

Open Cursor Settings, enable the server, and restart the chat.

Windsurf config

Windsurf uses ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "pdfmux": {
      "command": "npx",
      "args": ["-y", "pdfmux"]
    }
  }
}

VS Code Copilot config

VS Code Copilot (with MCP support enabled) reads workspace .vscode/mcp.json or user settings:

{
  "servers": {
    "pdfmux": {
      "command": "npx",
      "args": ["-y", "pdfmux"]
    }
  }
}

One config pattern, four clients. That is the whole point of MCP (see the official MCP specification).

The four tools and when to use each

1. analyze_pdf (fast triage)

Runs in under 500 ms on a 50-page document. Returns page count, detected languages, whether pages are digital or scanned, estimated extraction difficulty, and rough table count. Useful before you pay for a full extraction.

Example prompt in Claude Desktop:

“Quickly check /Users/me/Downloads/contract.pdf and tell me if it is a scanned document.”

Returned JSON:

{
  "page_count": 14,
  "languages": ["en"],
  "pages_digital": 2,
  "pages_scanned": 12,
  "estimated_tables": 3,
  "difficulty": "high",
  "recommended_tool": "convert_pdf"
}

The agent now knows it will need OCR, and can warn the user about longer processing time instead of silently truncating output.

2. convert_pdf (full extraction to Markdown)

The main workhorse. Runs the full multi-pass pipeline and returns clean Markdown plus per-page confidence scores.

Example prompt in Cursor:

“Convert specs/product-requirements.pdf to Markdown and summarize the non-functional requirements.”

Returned payload (trimmed):

{
  "markdown": "# Product Requirements\n\n## 1. Overview\n...",
  "pages": [
    {"page": 1, "confidence": 0.98, "method": "pymupdf"},
    {"page": 2, "confidence": 0.94, "method": "pymupdf"},
    {"page": 3, "confidence": 0.71, "method": "ocr"},
    {"page": 4, "confidence": 0.89, "method": "pymupdf"}
  ],
  "overall_confidence": 0.88,
  "warnings": [
    "Page 3 used OCR fallback. Review for accuracy."
  ]
}

The confidence scores are the important part. When the model sees page 3 at 0.71, it knows to either re-prompt the user or qualify its answer. Silent failure is the enemy of useful agents. For the full story on how this works under the hood, see self-healing PDF extraction.

3. extract_structured (tables and key-values)

Pulls tables as JSON and key-value pairs as an object. No more asking the model to regex through Markdown tables.

Example prompt in Claude Desktop:

“Extract the line items from invoice-q1-2026.pdf and sum the totals.”

Returned payload:

{
  "tables": [
    {
      "page": 1,
      "title": "Line Items",
      "headers": ["Item", "Qty", "Unit Price", "Total"],
      "rows": [
        ["Consulting hours", "40", "$220", "$8,800"],
        ["Platform license", "1", "$2,400", "$2,400"],
        ["Travel expenses", "1", "$1,150", "$1,150"]
      ]
    }
  ],
  "key_values": {
    "invoice_number": "INV-2026-0041",
    "invoice_date": "2026-03-31",
    "due_date": "2026-04-30",
    "total_amount": "$12,350.00",
    "currency": "USD"
  }
}

The model computes $8,800 + $2,400 + $1,150 = $12,350 against the total_amount and flags any discrepancy. No hallucinated sums.

4. batch_convert (directory processing)

Walks a directory, extracts every PDF, and returns a manifest. Useful for RAG ingestion pipelines (see PDF extraction for RAG pipelines) or bulk compliance audits.

Example prompt in Windsurf:

“Convert every PDF under /data/tenant-reports/2026-q1/ to Markdown and list any with confidence below 0.80.”

Returned payload:

{
  "processed": 47,
  "failed": 0,
  "low_confidence": [
    {"file": "tenant-report-14.pdf", "confidence": 0.72},
    {"file": "tenant-report-29.pdf", "confidence": 0.68}
  ],
  "output_dir": "/data/tenant-reports/2026-q1/_markdown/"
}

How PDFMux MCP compares to the alternatives

PDFMux is the only one that returns a quality signal. Every other server assumes the extraction worked. That assumption is wrong on roughly 30 percent of real-world PDFs (see the real-world PDF benchmark for the full breakdown).

Bottom line: if your agent needs to read PDFs it has never seen before, confidence scoring is the difference between correct answers and confident hallucinations.

Three agent workflows that actually work

Workflow 1: Contract review in Claude Desktop

Drop a folder of vendor contracts. Ask Claude:

“Review every PDF in /contracts/new-vendors/. Flag any with unusual termination clauses, payment terms over net 60, or auto-renewal language.”

Claude calls batch_convert, gets 14 markdown files with confidence scores, re-reads each one, and returns a table with file name, clause location, and quoted text. If any file scored below 0.85 it tells you so you can double check manually.

Workflow 2: Spec-to-code in Cursor

Point Cursor at a product requirements PDF:

“Read specs/checkout-flow.pdf and scaffold the TypeScript interfaces and API routes for the flows described in section 3.”

Cursor calls convert_pdf, extracts the spec with table preservation intact, and generates typed code that actually matches the document. No manual copy paste.

Workflow 3: Expense processing in Windsurf

“Extract all invoices in ~/Downloads/expenses-march/ and generate a CSV with date, vendor, amount, and category.”

Windsurf calls batch_convert then extract_structured on each file, aggregates the key-values, and writes a CSV. Works on mixed bilingual invoices because of the Arabic OCR support.

Performance and resource usage

• Cold start: about 8 seconds on first install, under 200 ms after.
• Memory: 180 MB baseline, peaks around 600 MB during OCR.
• CPU only: no GPU required (see PDF extraction without GPU for why).
• Privacy: everything runs locally by default. The LLM fallback step is optional and can be disabled with PDFMUX_LLM_FALLBACK=false, or replaced with a local model (see running PDF extraction locally with Gemma 4).

Registry availability

PDFMux MCP is published to every major MCP registry so your agent will find it through whichever discovery path it uses:

• Smithery
• PulseMCP
• mcp.so
• Glama
• Official MCP registry

One npm command, one config entry, every registry. That is the install experience we wanted.

Conclusion

Most PDF MCP servers give your agent the ability to read a clean digital PDF. PDFMux gives your agent the ability to read any PDF and know when it failed. Install with npx -y pdfmux, drop the config into Claude Desktop, Cursor, Windsurf, or VS Code Copilot, and your agent stops hallucinating document contents.

If you are building agents that touch real business documents (contracts, invoices, reports, compliance filings) the confidence signal is not optional. It is the difference between an agent you can trust and an agent that sounds confident while being wrong.