Pdf Extract MCP Server

pdf-extract-mcp

A Model Context Protocol (MCP) server that extracts tables and text from digital (text-layer) PDFs — bank statements, invoices, bills — into CSV / JSON / Excel, with automatic PII redaction.

Part of the invoice-extractor product. This package is the MCP distribution channel ("ecosystem parasite": one backend, many host workflows). Web demo lives in the parent project.

What it does

• extract_pdf — upload a digital PDF (base64 or URL), get back structured table rows as CSV / JSON records / XLSX. Sensitive fields are masked by default: national ID, phone, bank card, unified social credit code, email, passport, Chinese personal names, organization names.
• health — service status and free-tier limits.

Scanned / image-only PDFs are explicitly rejected (SCANNED_PDF_UNSUPPORTED) — the free tier covers digital PDFs only (OCR is a paid-tier candidate).

Limits (free tier)

• 100 pages / rolling 30 days / client (anonymous, keyed by client hash).
• 50 MB per file.
• Above quota the tool returns a structured QUOTA_EXCEEDED response with an in-band upgrade pointer. It never silently bills.
• Set PDF_EXTRACT_API_KEY to a paid key to bypass the quota (billing gateway is a P1 item; current free tier has no paid keys issued).

Run (local stdio — Claude Desktop / Cursor / any MCP client)

pip install -e .
pdf-extract-mcp

Client config example:

{
  "mcpServers": {
    "pdf-extract": {
      "command": "pdf-extract-mcp",
      "env": {}
    }
  }
}

Run (remote streamable-http, for hosted MCP clients)

REMOTE_TRANSPORT=http MCP_HOST=127.0.0.1 MCP_PORT=5060 \
  python -m pdf_extract_mcp.server
# POST JSON-RPC to http://127.0.0.1:5061/mcp

Tool schema

extract_pdf(
  pdf_base64: str | None,     # preferred: PDF bytes as base64
  pdf_url:    str | None,     # alternative: direct https .pdf URL
  output:     "csv"|"json"|"xlsx",   # default csv
  redact_pii: bool = true,
  api_key:    str | None,    # paid key, optional
) -> {
  ok, type: "tables"|"text", pages, tables, rows, columns,
  csv | rows_json | xlsx_base64,   # depends on output
  elapsed_ms
}

Telemetry

Every call is appended (best-effort, never blocks extraction) to ../state/mcp_usage.jsonl. The P0 validation metric is real non-self traffic: third-party agents discovering and calling the server, not our own tests. Clients are recorded as salted hashes, no PDF content is logged.

Stack

mcp >= 1.2 (works on both mcp 1.x FastMCP and mcp 2.x MCPServer), pdfplumber, pandas, openpyxl. Python 3.10+.

License

MIT