Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Invoice Bridge MCP Validate the latest invoice PDF against § 14 UStG and EN 16931."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Ein robuster, produktionsreifer Model Context Protocol (MCP) Server zur automatisierten Extraktion, Analyse und Konformitätsprüfung von hybriden elektronischen Rechnungen (ZUGFeRD / Factur-X) und § 14 UStG Pflichtangaben für KI-Assistenten (z. B. Claude Desktop, Antigravity, Cursor, Cline).
Related MCP server: Scribo MCP Server
Ab dem 01.01.2025 gilt in Deutschland die gesetzliche Verpflichtung zum Empfang elektronischer Rechnungen (E-Rechnung) im B2B-Bereich. Invoice Bridge MCP schließt die Lücke zwischen Dokumenten-Eingangsverzeichnissen, hybriden PDF/A-3-Rechnungsdateien und LLM-basierten Agenten.
Der MCP-Server ermöglicht KI-Assistenten:
Rechnungsdokumente im Eingangsordner aufzufinden (invoices://list).
Eingebettete XML-Rechnungsdaten aus PDF/A-3-Dateien verlustfrei zu extrahieren (parse_invoice).
XML-Rechnungen auf steuerrechtliche (§ 14 UStG) und EN 16931 Konformität zu prüfen (validate_compliance).
PDF-Rechnungen in einem Schritt direkt zu prüfen (validate_invoice_pdf).
📄 PDF/A-3 Extraktion: Erkennt und extrahiert eingebettete Factur-X / ZUGFeRD-Anhänge (factur-x.xml, zugferd-invoice.xml, xrechnung.xml).
⚡ 1-Step PDF Validierung: Direkte Prüfung von PDF-Rechnungen ohne Zwischendatei.
🛡️ Sicherheit & Resilienz: Integrierte Path-Traversal-Absicherung (.. Erkennung) und sicheres Fehlerhandling bei defektem XML.
⚖️ § 14 UStG & Schematron-Validierung:
Rechnungsnummer, Ausstellungsdatum (Format 102 / YYYYMMDD), Rechnungstyp-Codes.
Vollständigkeit von Rechnungssteller und Leistungsempfänger.
Prüfung der Steuernummer und USt-IdNr. (Format & ISO-Ländercode-Prefix).
Währungscodes (ISO 4217) & Ländercodes (ISO 3166-1).
🧮 Mathematische Konsistenzprüfung:
Exakte Cent-genaue Prüfung mit Decimal: Netto + USt == Brutto.
Prüfung der maximalen Nachkommastellen (BR-DEC-Regeln).
🔌 Standardkonformes MCP: Basiert auf FastMCP mit automatischer Tool- und Ressourcen-Registrierung.
flowchart LR
A[KI-Agent / LLM] <-->|MCP Protocol| B[Invoice Bridge MCP Server]
B --> C[parser.py\nPDF/A-3 Extractor]
B --> D[validator.py\nFacturXValidator]
B --> E[(input/ Ordner)]
C -->|Liest PDF & Schreibt XML| E
D -->|Liest XML & Prüft Daten| EPython >= 3.10
Virtuelle Umgebung empfohlen
git clone https://github.com/Winterholdt/invoice-bridge-mcp.git
cd invoice-bridge-mcp
# Virtual Environment anlegen
python -m venv .venv
# Aktivieren (Windows PowerShell)
.venv\Scripts\Activate.ps1
# Aktivieren (Linux/macOS)
source .venv/bin/activatepip install -e .Trage den MCP Server in deine Konfigurationsdatei (z. B. claude_desktop_config.json) ein:
{
"mcpServers": {
"invoice-bridge": {
"command": "c:/your/path/invoice-bridge-mcp/.venv/Scripts/python.exe",
"args": [
"c:/your/path/invoice-bridge-mcp/src/invoice_bridge/server.py"
],
"env": {
"INVOICE_INPUT_DIR": "c:/your/path/invoice-bridge-mcp/input"
}
}
}
}Variable | Standardwert | Beschreibung |
|
| Absoluter oder relativer Pfad zum Eingangsverzeichnis für Rechnungen. |
URI | Beschreibung | Rückgabe |
| Listet alle im Eingangsordner ( | Liste von Dateinamen ( |
validate_invoice_pdf (Empfohlen für PDFs)Direkte Prüfung einer PDF-Rechnung in einem Schritt: Extrahiert eingebettete ZUGFeRD/Factur-X XML-Daten und validiert die Konformität nach § 14 UStG.
Eingabe-Parameter:
invoice_pdf_name (string, erforderlich): Dateiname der PDF im Ordner input/ (z. B. test.pdf).
Rückgabe-Beispiel:
{
"status": "success",
"invoice_id": "RE-2026-001",
"compliance_checks": {
"is_valid": true,
"total_checks": 14,
"passed": 14,
"failed": 0,
"failed_details": []
},
"approved_for_payment": true
}parse_invoiceExtrahiert die eingebettete ZUGFeRD/Factur-X XML-Datei aus einer PDF-Rechnung und speichert sie als .xml im Eingangsordner.
Eingabe-Parameter:
invoice_pdf_name (string, erforderlich): Dateiname der PDF im Ordner input/ (z. B. test.pdf).
Rückgabe-Beispiel:
{
"status": "success",
"xml_file": "test.xml"
}validate_compliancePrüft eine vorhandene ZUGFeRD/Factur-X XML-Datei auf formale, strukturelle und rechnerische Konformität nach § 14 UStG und EN 16931 / Factur-X Profilen.
Eingabe-Parameter:
invoice_xml_name (string, erforderlich): Dateiname der XML im Ordner input/ (z. B. test.xml).
Rückgabe-Beispiel:
{
"status": "success",
"invoice_id": "INV-2026-001",
"compliance_checks": {
"is_valid": true,
"total_checks": 14,
"passed": 14,
"failed": 0,
"failed_details": []
},
"approved_for_payment": true
}Regel-ID | Standard / Norm | Beschreibung |
BR-01 | EN 16931 / Factur-X | Profil-Spezifikation (Specification Identifier / BT-24) |
BR-02 | § 14 Abs. 4 Nr. 4 UStG | Fortlaufende Rechnungsnummer (BT-1) |
BR-03 | § 14 Abs. 4 Nr. 3 UStG | Ausstellungsdatum im Format 102 ( |
BR-04 | UN/CEFACT 1001 | Gültiger Rechnungstyp-Code (z. B. |
BR-05 | ISO 4217 | 3-stelliger Währungscode (BT-5, z. B. |
BR-06 | § 14 Abs. 4 Nr. 1 UStG | Name des Rechnungsstellers (Seller Name / BT-27) |
BR-07 | § 14 Abs. 4 Nr. 1 UStG | Name des Rechnungsempfängers (Buyer Name / BT-44) |
BR-09 | ISO 3166-1 | Ländercode des Rechnungsstellers (BT-40) |
BR-CO-26 | EN 16931 | Rechnungssteller-Identifikation (Seller ID, Legal Org ID, Tax ID) |
BR-CO-09 | § 14 Abs. 4 Nr. 2 UStG | USt-IdNr. mit korrektem Länder-Präfix oder Steuernummer |
BR-13..15 | EN 16931 | Pflichtsummen: Netto ( |
BR-DEC-* | EN 16931 | Maximal 2 Nachkommastellen bei Währungsbeträgen |
CALC-01 | § 14 Abs. 4 Nr. 7/8 UStG | Mathematische Konsistenz: |
invoice-bridge-mcp/
├── .github/
│ └── workflows/
│ └── ci.yml # GitHub Actions CI Workflow (Python 3.10 - 3.12)
├── config/
│ └── mcp_config.example.json # Vorlage für MCP-Client-Konfiguration
├── input/ # Verzeichnis für Eingangsrechnungen (PDF/XML)
│ └── test.pdf
├── src/
│ └── invoice_bridge/ # Hauptpaket (Single Source of Truth)
│ ├── __init__.py
│ ├── parser.py # PDF/A-3 Extractor mit robuster Fehlerbehandlung
│ ├── server.py # FastMCP Server mit Path-Traversal-Schutz
│ └── validator.py # FacturX / ZUGFeRD / § 14 UStG Prüflogik
├── test_invoices/ # Testrechnungen
│ ├── fail-xml-invalid.pdf
│ └── test.pdf
├── tests/ # Vollständige Pytest-Suite
│ ├── test_parser.py
│ ├── test_server.py
│ └── test_validator.py
├── .gitignore
├── pyproject.toml # Projekt-Metadaten, Entrypoints & Linter-Settings
└── README.md# Entwicklungsumgebung inkl. Test-Tools installieren
pip install -e .[dev]
# Linter ausführen
ruff check .
# Test-Suite ausführen
pytest -vDieses Projekt ist unter der MIT-Lizenz lizenziert. Weitere Details in der LICENSE-Datei.
Extrahiert die eingebetteten XML-Daten aus einer PDF/A-3-Datei und speichert sie im Eingangsordner.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_pdf_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose one important non-obvious behavior: the extracted XML is written into a target folder rather than just returned. However, it says nothing about where that folder is, whether an existing file is overwritten, permissions, or error behavior on a malformed/non-PDF-A-3 input.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler, front-loading the extraction action before the persistence side effect. It is appropriately sized for a one-parameter tool; there is simply very little content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-required-parameter tool with no output schema, the description covers the core action and the write side effect. It is still thin on the details an agent would want before invoking a tool that mutates a filesystem: destination folder, overwrite semantics, and failure modes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description is the only source of parameter meaning. It usefully implies the input is a PDF/A-3 file, but it never clarifies whether 'invoice_pdf_name' is a bare filename, a relative path, or an absolute path, nor whether the file must already be in a specific location.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb pair (extracts XML, saves it) and a specific resource (embedded XML data in a PDF/A-3 file), which is enough to separate it from validate_invoice_pdf and validate_compliance. It stops short of explicitly contrasting itself with those siblings, so a 5 is not warranted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to call this tool versus the two sibling validators, no prerequisites, and no exclusions. The use case is only inferable from the tool name and the mention of PDF/A-3 - which is implied guidance at best.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Prüft eine ZUGFeRD/Factur-X-XML-Datei auf formale und rechnerische Konformität nach § 14 UStG und EN 16931.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_xml_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It implies a read-only check but never states that the file is not modified, what permissions are needed, whether a file must already exist, or how failures are reported.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with the verb first and zero filler. Nothing could be removed without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should at least sketch the validation result (pass/fail, error list) and failure behavior. It states the check's scope but leaves the return contract and error semantics entirely unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single required parameter. The description partially compensates by specifying that the input is a ZUGFeRD/Factur-X XML file, giving the agent format context, but adds no naming/path convention beyond the parameter name invoice_xml_name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Prüft/validates) and resource (ZUGFeRD/Factur-X XML file) plus the standards applied (§ 14 UStG, EN 16931). The mention of an XML file implicitly separates it from the sibling validate_invoice_pdf, but no sibling is named or explicitly contrasted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to pick this over parse_invoice or validate_invoice_pdf, and no prerequisites (e.g. must the file be uploaded first, does it need to be a local path). Usage can only be inferred from 'XML-Datei'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Direkte Prüfung einer PDF-Rechnung in einem Schritt: Extrahiert eingebettete ZUGFeRD/Factur-X XML-Daten und validiert die Konformität nach § 14 UStG.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_pdf_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does disclose real behavior beyond the name: the tool extracts embedded ZUGFeRD/Factur-X XML and validates against § 14 UStG, implying a read-only operation scoped to compliant e-invoice PDFs. It does not say what happens when no embedded XML is present, nor how results or failures are surfaced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact clauses: the purpose ('Direkte Prüfung einer PDF-Rechnung in einem Schritt') is front-loaded, followed by the mechanism. Every phrase carries information, though the framing colon structure is slightly less scannable than a single sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description must cover the full picture. It explains what is extracted and which standard is applied, but omits return shape (pass/fail, error list) and edge cases such as PDFs without embedded XML, leaving meaningful gaps for a validation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the single parameter 'invoice_pdf_name' is undocumented in the schema. The description partially compensates by establishing that the input must be a PDF invoice carrying embedded ZUGFeRD/Factur-X XML, which narrows the expected file type, but it gives no format, path, or naming guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Prüfung/validiert) and resource (PDF-Rechnung), and clarifies the mechanism: extracting embedded ZUGFeRD/Factur-X XML and checking conformity with § 14 UStG. The phrase 'in einem Schritt' implicitly distinguishes it from the parse/validate sibling pair, but it stops short of naming them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'In einem Schritt' (in one step) hints that this is the combined alternative to calling parse_invoice and validate_compliance separately, but no sibling is named and no when-not condition is given. Usage is implied rather than explicit, so an agent must infer the routing decision.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0parse_invoicevalidate_compliancevalidate_invoice_pdfScored across 3 tools
parse_invoice and validate_invoice_pdf both extract embedded XML from PDFs, creating overlap. Descriptions clarify that parse_invoice only extracts and saves, while validate_invoice_pdf also validates, and validate_compliance validates standalone XML, but the extraction overlap still causes potential confusion.
All tools follow a consistent snake_case verb_noun pattern (parse_invoice, validate_compliance, validate_invoice_pdf). The convention is predictable and easy to understand.
Three tools is slightly below the typical 3-15 range but each serves a distinct purpose (extraction, XML validation, PDF validation). However, some redundancy between parse_invoice and validate_invoice_pdf suggests the set could be streamlined.
The server covers extraction and validation of ZUGFeRD/Factur-X invoices, but lacks tools for generating or converting invoices, which might be expected from an 'Invoice Bridge'. This is a notable gap for a domain that often requires bridging between formats.
German e-invoicing: generate XRechnung 3.0, pre-check and extract (incl. ZUGFeRD PDF). Paid.
Evidence-backed UBL, PDF, and image invoice checks before approval or payment.
XRechnung and ZUGFeRD e-invoicing (EN 16931): create, validate, check Leitweg-IDs, German VAT.
Create ZUGFeRD e-invoices from JSON or PDF, verify Factur-X, check VAT IDs and Peppol.
