pdf-extract-mcp

Ein Model Context Protocol (MCP)-Server, der strukturierte Daten aus unstrukturierten PDF-Dokumenten deterministisch extrahiert – reine Textextraktion plus Regex-/Heuristik-Feldabgleich, ohne LLM-API-Aufrufe zur Extraktionszeit.

Funktionen

• Echter MCP-Server – basierend auf dem offiziellen MCP Python SDK (2.x), das das Protokoll über stdio, SSE oder streamable HTTP spricht. Verifiziert durch einen End-to-End-Test, der den tatsächlichen Server mit dem offiziellen Client steuert.

• Schema-gesteuerte Extraktion – richten Sie extract_fields auf ein beliebiges JSON Schema aus und erhalten Sie strukturiertes JSON genau für die Felder, die Sie angefordert haben.

• Deterministisch und überprüfbar – Regex-/Heuristik-Abgleich, keine LLM-API-Aufrufe, keine versteckten Kosten, keine Black Box. Jede Extraktion ist wiederholbar und nachvollziehbar.

• Verständliche Validierungsberichte – validate_against_schema erklärt pro Feld, warum es bestanden hat, fehlgeschlagen ist oder fehlt.

• Vorgefertigte Schemas – invoice, resume und purchase_order sind sofort einsatzbereit, dazu synthetische Beispiel-PDFs, sodass alles direkt demonstrierbar ist.

• Saubere Fehlerbehandlung – beschädigte PDFs, fehlende Dateien und ungültige Schemas liefern strukturierte Fehler, niemals Stack-Traces.

Related MCP server: PDF RAG MCP Server

Was ist MCP und warum ist das nützlich?

Das Model Context Protocol ist ein offener Standard, der KI-Assistenten (Claude, Cursor usw.) ermöglicht, über eine persistente, bidirektionale Verbindung externe Werkzeuge aufzurufen. Anstatt PDF-Text in einen Chat einzufügen und das Modell zu bitten, ihn zu „interpretieren“, kann ein Assistent pdf-extract-mcp direkt aufrufen, strukturiertes JSON empfangen, das einem von Ihnen bereitgestellten Schema entspricht, und darauf reagieren. Da die Extraktion hier deterministisch ist (Regex + Heuristiken) – kein probabilistischer Modellaufruf – ist jedes Ergebnis überprüfbar, wiederholbar und kostengünstig. Das macht es ideal für automatisierte Dokumentpipelines (Rechnungen an die Buchhaltung, Lebensläufe an ATS, Bestellungen an den Einkauf), bei denen Sie wissen müssen, warum ein Feld auf eine bestimmte Weise extrahiert wurde.

Installation

cd pdf-extract-mcp
python3 -m venv .venv
source .venv/bin/activate
make install          # pip install -e ".[dev]"  (installs the console script too)

oder mit einfachem pip:

pip install -e ".[dev]"

Der Server verwendet das offizielle MCP Python SDK (mcp >= 2.x, die aktuelle Release-Linie, die die MCPServer-API bereitstellt). pdfplumber übernimmt die Textextraktion, jsonschema die Validierung und reportlab erzeugt die Beispiel-PDFs.

Die Installation stellt außerdem ein pdf-extract-mcp-Konsolenskript bereit, sodass Sie den Server von überall aus mit folgendem Befehl ausführen können:

pdf-extract-mcp                     # stdio (default)
pdf-extract-mcp --transport streamable-http --host 127.0.0.1 --port 8000

Ausführen

python server.py

Dies stellt MCP über stdio bereit (die Standardeinstellung und das, was Claude Code / Claude Desktop erwarten). Sie können es auch als Netzwerkdienst bereitstellen:

python server.py --transport streamable-http --host 127.0.0.1 --port 8000
python server.py --transport sse --host 127.0.0.1 --port 8001

Verbindung zu Claude Code / Claude Desktop herstellen

Claude Code – fügen Sie eine .mcp.json im Projektstamm hinzu:

{
  "mcpServers": {
    "pdf-extract": {
      "command": "python",
      "args": ["/absolute/path/to/pdf-extract-mcp/server.py"],
      "env": {}
    }
  }
}

Claude Desktop – fügen Sie denselben Block zur Claude Desktop config hinzu (claude_desktop_config.json, auf macOS unter ~/Library/Application Support/Claude/ zu finden):

{
  "mcpServers": {
    "pdf-extract": {
      "command": "python",
      "args": ["/absolute/path/to/pdf-extract-mcp/server.py"]
    }
  }
}

Starten Sie den Client nach dem Speichern neu. Sie sollten drei neue Werkzeuge sehen: extract_fields, validate_against_schema und list_supported_document_types.

Werkzeuge

Das schema-Argument von extract_fields akzeptiert ein JSON-Schema-Objekt, einen integrierten Schema-Namen (z. B. „invoice“) oder einen Pfad zu einer .json-Schemadatei. Integrierte Schemas befinden sich in schemas/:

• invoice – vendor_name, invoice_number, total_amount, due_date (erforderlich) + issue_date, customer_name

• resume – name, email (erforderlich) + phone, skills

• purchase_order – po_number, vendor_name, total_amount (erforderlich) + issue_date, customer_name

Arbeitsbeispiel

Generieren Sie zuerst die Beispiel-PDFs (bereits im Repository vorhanden; jederzeit neu erzeugen mit):

python sample_pdfs/generate_samples.py

Rufen Sie nun extract_fields für die Beispielrechnung mit dem integrierten Schema-Namen invoice auf. In Claude Code können Sie einfach sagen: „Extract the fields from sample_pdfs/invoice.pdf using the invoice schema“; im Hintergrund wird ein Tool-Aufruf ausgeführt, der Folgendem entspricht:

{
  "name": "extract_fields",
  "arguments": {
    "pdf_path": "/absolute/path/to/pdf-extract-mcp/sample_pdfs/invoice.pdf",
    "schema": "invoice"
  }
}

Tatsächlich erwartetes Ergebnis:

{
  "ok": true,
  "data": {
    "vendor_name": "Acme Widgets Corp",
    "invoice_number": "INV-2024-0087",
    "total_amount": 1750.0,
    "due_date": "April 1, 2024",
    "issue_date": "March 1, 2024",
    "customer_name": "Globex Industries"
  },
  "text_length": 372
}

Wenn Sie dieselben Daten mit demselben Schema an validate_against_schema übergeben:

{
  "ok": true,
  "valid": true,
  "passed": ["customer_name", "due_date", "invoice_number", "issue_date", "total_amount", "vendor_name"],
  "failed": [],
  "missing": [],
  "summary": "Valid: all 6 present field(s) conform to the schema.",
  "error": null
}

Führen Sie diese direkt aus Python aus, um es live zu sehen:

import json
from tools.extract import extract_fields
from tools.validate import validate_against_schema

schema = json.load(open("schemas/invoice.json"))
result = extract_fields("sample_pdfs/invoice.pdf", schema)
print(result["data"])
print(validate_against_schema(result["data"], schema))

So funktioniert die MCP-Toolregistrierung in server.py

Das ist der Kern des Projekts, daher lohnt es sich, genau zu verstehen, was das SDK für Sie übernimmt.

1. Das Server-Objekt erstellen.

from mcp.server.mcpserver import MCPServer

mcp = MCPServer(
    "pdf-extract-mcp",
    title="PDF Extract MCP",
    description="Deterministic structured-data extraction from PDF documents",
    version="0.2.0",
)

MCPServer ist die Serverklasse des mcp SDK 2.x. Sie implementiert das MCP-Wire-Protokoll: Sie weiß, wie sie auf die JSON-RPC-Nachrichten antwortet, die ein Client während des MCP-Handshakes sendet (initialize, tools/list, tools/call usw.). Die Konstruktorargumente sind Metadaten – der Server-Name (für den Protokoll-Handshake erforderlich) plus optionale title/description/version, die Clients dem Benutzer anzeigen können.

2. Jedes Werkzeug mit einem Dekorator registrieren.

@mcp.tool()
def extract_fields(pdf_path: str, schema: dict) -> dict:
    """Extract structured fields from an unstructured PDF ..."""
    return _extract_fields(pdf_path, schema)

Der Dekorator übernimmt für Sie drei Aufgaben:

• Namensregistrierung – der Funktionsname extract_fields wird zum Tool-Namen, mit dem ein Client es aufruft. (Sie können ihn mit @mcp.tool(name="...") überschreiben.)

• Schema-Ableitung – das SDK untersucht die Typannotationen der Funktion (pdf_path: str, schema: dict) und erzeugt das JSON-Eingabeschema des Werkzeugs automatisch. Deshalb weiß der MCP-Client bereits vor dem Aufruf, dass pdf_path ein String und schema ein Objekt ist. Es ist dasselbe Muster, das FastAPI verwendet – Typen sind der Vertrag.

• Beschreibung – der Docstring wird zur Beschreibung des Werkzeugs, die Claude liest, um zu entscheiden, wann das Werkzeug mit welchen Argumenten aufgerufen wird.

Wenn ein Client den Server also fragt: „Was kannst du tun?“ (tools/list), antwortet das SDK mit Name, Beschreibung und abgeleitetem Eingabeschema für jede dekorierte Funktion – keine manuelle Registrierungstabelle, die synchron gehalten werden muss.

3. Der Funktionsrumpf ist einfach Python.

Wenn ein Client das Werkzeug aufruft (tools/call mit Argumenten), deserialisiert das SDK die JSON-Argumente, ruft Ihre Funktion mit ihnen auf und serialisiert den Rückgabewert über die Leitung zurück. Der Rückgabewert ist das, was der Client sieht – deshalb geben die Werkzeuge immer einfache JSON-fähige Dictionaries zurück und werfen niemals eine Exception: Eine Ausnahme würde zu einem undurchsichtigen Protokollfehler, während ein strukturiertes {"ok": false, "error": "..."}-Dictionary etwas ist, das Claude lesen und darauf reagieren kann. Die eigentliche Extraktions-/Validierungslogik liegt in tools/extract.py und tools/validate.py, sodass sie ohne MCP-Client unit-testbar bleibt.

4. Ausführen.

if __name__ == "__main__":
    main()   # argparse -> mcp.run(transport="stdio")

mcp.run(transport="stdio") startet die Protokollschleife: Sie liest zeilenweise begrenzte JSON-RPC-Anfragen von stdin, verteilt sie an die registrierten Werkzeuge und schreibt Antworten nach stdout. Das ist der gesamte Server – kein HTTP-Framework, keine Routen, keine manuelle Anfrageverarbeitung. (Für streamable-http / sse startet derselbe run()-Aufruf eine interne ASGI-App.)

Ein weiteres Detail, das erwähnenswert ist: extract_fields verwendet einen kleinen Helfer _load_schema, der ein Schema-Dictionary, einen integrierten Schema-Namen oder einen Dateipfad akzeptiert – sodass dasselbe Werkzeug mit „invoice“ oder einem vollständigen Schema-Objekt funktioniert. Die eigentliche Extraktionsfunktion bleibt strikt (nur Dictionary) und die Serverebene übernimmt die Komfortkonvertierungen.

So funktioniert die Extraktion (deterministisch, überprüfbar)

1. Textextraktion – pdfplumber öffnet die PDF und extrahiert den Klartext von jeder Seite.

2. Feldabgleich – für jede Eigenschaft in Ihrem Schema wird eine geordnete Liste von Regexes durchsucht; der erste Treffer gewinnt (tools/extract.py -> _FIELD_PATTERNS). Die Muster sind zuerst am spezifischsten, und unbekannte Feldnamen fallen auf einen generischen Abgleich „Feldname: Wert“ zurück, zusätzlich zu einer Synonymtabelle (_FIELD_ALIASES).

3. Typumwandlung – übereinstimmende Strings werden in den JSON-Schema-Typ umgewandelt (z. B. „$1.750,00“ -> 1750.0 für „type“: „number“; bei Arrays durch Komma getrennt). Schlägt die Umwandlung fehl, wird der rohe String verwendet, statt Daten zu verlieren.

4. Validierung – validate_against_schema prüft die extrahierten Daten erneut mit dem Paket jsonschema und meldet pro Feld, ob es bestanden hat, fehlgeschlagen ist (mit verständlicher Begründung) oder vollständig fehlt.

Da jeder Schritt einfacher Code ist, können Sie genau nachvollziehen, warum ein Feld extrahiert wurde oder nicht – keine Black Box.

Fehlerbehandlung

Alle drei Werkzeuge geben auf jedem Pfad strukturiertes JSON zurück – sie werfen niemals einen Stack-Trace über die MCP-Grenze hinweg:

• Beschädigte/nicht lesbare PDF -> {"ok": false, "error": "Could not read PDF ..."}

• Nicht vorhandene Datei -> {"ok": false, "error": "PDF not found: ..."}

• PDF ohne extrahierbaren Text -> {"ok": false, "error": "... contains no extractable text."}

• Ungültiges Schema (leer, ohne Properties oder ungültiges JSON Schema) -> strukturierter Fehlerschlüssel

• Fehlende Pflichtfelder -> werden unter „missing“ aufgelistet; fehlerhafte Werte -> unter „failed“ mit Begründungen

Tests

pytest tests/ -v

19 Tests, die Folgendes abdecken:

• Erfolgreiche Extraktion für alle drei Dokumenttypen (invoice, resume, purchase_order)

• Eine PDF mit fehlenden Pflichtfeldern (negative Extraktion)

• Schema-Validierung, die einen fehlerhaften Feldtyp, fehlende Pflichtfelder und Enum/Pattern-Verstöße erkennt

• Fehlerpfade: beschädigte PDF, nicht vorhandene Datei, PDF ohne Text, ungültiges Schema

• Ein echter End-to-End-MCP-Test (tests/test_mcp_end_to_end.py), der server.py als Unterprozess startet, über stdio mit dem offiziellen MCP-Client verbindet und alle drei Werkzeuge über die Leitung aufruft – das beweist, dass es sich um einen echten MCP-Server handelt, nicht um eine Bibliothek, die so tut

Beispiel-PDFs werden bei Bedarf von tests/conftest.py automatisch neu erzeugt.

Repository-Struktur

pdf-extract-mcp/
  server.py                    # MCP server: MCPServer + tool registration + transports
  tools/
    __init__.py
    extract.py                 # pdfplumber text extraction + regex field matching
    validate.py                # jsonschema validation with structured reports
  schemas/
    invoice.json               # pre-built schema: invoice
    resume.json                # pre-built schema: resume
    purchase_order.json        # pre-built schema: purchase_order
  sample_pdfs/
    generate_samples.py        # reportlab generator for the 4 sample PDFs
    invoice.pdf
    invoice_missing_fields.pdf
    resume.pdf
    purchase_order.pdf
  tests/
    conftest.py                # auto-generates sample PDFs if missing
    test_tools.py              # unit tests for extract/validate
    test_mcp_end_to_end.py     # end-to-end test over the real MCP stdio transport
  README.md
  requirements.txt

Fehlerbehebung

• ModuleNotFoundError: No module named 'mcp' – Sie befinden sich nicht in der virtuellen Umgebung: source .venv/bin/activate (oder ./.venv/bin/python server.py verwenden).

• FastMCP-Importfehler – server.py zielt auf die mcp-2.x-API (MCPServer). Wenn Ihre Umgebung mcp 1.x hat, installieren Sie neu mit pip install -U "mcp>=2.0".

• Werkzeuge erscheinen nicht in Claude – starten Sie den Client nach dem Bearbeiten der Konfiguration neu und stellen Sie sicher, dass „args“ auf den absoluten Pfad zu server.py zeigt, wobei bei Bedarf das Python der venv als Befehl verwendet wird.

• Extraktion übersieht ein Feld – fügen Sie ein Muster dafür in _FIELD_PATTERNS in tools/extract.py hinzu (oder verlassen Sie sich auf den generischen „Feldname: Wert“-Fallback und die Synonymtabelle).