ZUGFeRD / XRechnung
MCP Validation Server

1. Übersicht

Der Server stellt drei Tools und eine Resource bereit, die von KI-Agenten über das Model Context Protocol aufgerufen werden können.

2. Architektur & Datenfluss

Ablauf für validate_invoice

3. Installation & Konfiguration

# Kostenlos registrieren:
https://zugferd-validator.de/portal.html

npm install -g zugferd-mcp-client

// mcp_config.json (je nach Client abweichender Pfad)
{
  "mcpServers": {
    "zugferd": {
      "command": "zugferd-mcp-client",
      "env": {
        "ZUGFERD_API_KEY": "zv_dein_key_hier"
      }
    }
  }
}

Direkte REST API

Die API kann auch direkt ohne MCP-Client angesprochen werden:

# Beispiel: Validierung per curl
curl -X POST https://api.zugferd-validator.de/v1/validate \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: zv_dein_key_hier" \
  -d '{"file_content":"<base64>","file_type":"xml"}'

Umgebungsvariablen (MCP-Client)

4. Tools

{
  "valid":   true,
  "format":  "ZUGFeRD 2.4 / Factur-X 1.0",
  "profile": "EN16931",
  "summary": "Keine Probleme gefunden",
  "errors":  [],
  "warnings": [],
  "metadata": {
    "invoice_number": "RE-2026-001",
    "issue_date":     "2026-04-01",
    "seller":         "Musterfirma GmbH",
    "buyer":          "Beispiel AG",
    "total_amount":   "1190.00",
    "currency":       "EUR"
  }
}

{
  "valid":   false,
  "format":  "ZUGFeRD 2.4 / Factur-X 1.0",
  "profile": "EN16931",
  "summary": "2 Fehler, 1 Warnung gefunden",
  "errors": [
    {
      "severity":       "error",
      "rule_id":        "BR-DE-1",
      "field":          "BT-31 / BT-32",
      "message":        "Die USt-ID (BT-31) oder Steuernummer (BT-32) muss angegeben werden.",
      "fix_suggestion": "Füge 'ram:SpecifiedTaxRegistration' mit schemeID='VA' und USt-ID hinzu.",
      "xpath":          "//ram:SellerTradeParty/ram:SpecifiedTaxRegistration"
    }
  ],
  "warnings": [
    {
      "severity":       "warning",
      "rule_id":        "BR-CL-10",
      "field":          "BT-81",
      "message":        "Zahlungsmittelcode muss aus UNTDID 4461 stammen.",
      "fix_suggestion": "Verwende z.B. '58' für SEPA-Überweisung oder '59' für SEPA-Lastschrift.",
      "xpath":          "//ram:SpecifiedTradeSettlementPaymentMeans/ram:TypeCode"
    }
  ]
}

{
  "xml_content": "<?xml version='1.0' encoding='UTF-8'?>\n<rsm:CrossIndustryInvoice ...>...</rsm:CrossIndustryInvoice>",
  "format":      "ZUGFeRD 2.4 / Factur-X 1.0",
  "profile":     "EN16931"
}

{
  "consistent":    true,
  "discrepancies": []
}

{
  "consistent":    false,
  "discrepancies": [
    {
      "field":     "total_amount",
      "pdf_value": "1190.00",
      "xml_value": "1180.00",
      "message":   "Gesamtbetrag im PDF ('1190.00') unterscheidet sich von dem im XML ('1180.00')."
    }
  ]
}

5. Resource: validation_rules

Gibt das aktuelle Regelwerk des Servers zurück: unterstützte Formate, Profile und die verwendete Validierungsengine.

URI: validation://rules

{
  "supported_formats": [
    "ZUGFeRD 1.0", "ZUGFeRD 2.0", "ZUGFeRD 2.1", "ZUGFeRD 2.2",
    "ZUGFeRD 2.3", "ZUGFeRD 2.4 / Factur-X 1.0",
    "XRechnung 1.2", "XRechnung 2.0", "XRechnung 2.3", "XRechnung 3.0"
  ],
  "supported_profiles": [
    "minimum", "basic_wl", "basic", "en16931", "extended", "xrechnung"
  ],
  "validation_engine": "Mustang Project v2.22.0",
  "last_updated":      "2026-04-01"
}

6. Fehlerbehandlung

Alle Tools geben bei Fehlern ein JSON-Objekt mit einem error-Feld zurück. Es gibt niemals eine unstrukturierte Fehlerausgabe.

{
  "error":   "Kurze Fehlerkategorie",
  "details": "Ausführliche Beschreibung mit konkretem Hinweis zur Behebung."
}

7. Gemeinsame Datentypen

ValidationIssue

Wird in den Arrays errors, warnings und notices von validate_invoice verwendet.

InvoiceMetadata

Optionales Feld im Ergebnis von validate_invoice (nur bei file_type: "xml").

8. Unterstützte Formate & Profile

Formate

Profile (ZUGFeRD/Factur-X)

9. Regelwerk & Korrekturvorschläge

Der Server enthält eine Datenbank mit Korrekturvorschlägen für 48 Regelkategorien. Wenn Mustang einen Fehler mit bekannter Regel-ID meldet, wird der Korrekturvorschlag automatisch angehängt.

10. Nutzungsbeispiele

Beispiel 1: XRechnung-XML validieren

{
  "tool": "validate_invoice",
  "arguments": {
    "file_content": "PD94bWwgdmVyc2lvbj0iMS4wIj8+...",
    "file_type":   "xml",
    "profile":     "xrechnung"
  }
}

{
  "valid":   true,
  "format":  "XRechnung 3.0",
  "profile": "XRECHNUNG",
  "summary": "Keine Probleme gefunden",
  "errors":  [],
  "warnings": [],
  "metadata": {
    "invoice_number": "INV-2026-0042",
    "issue_date":     "2026-04-07",
    "seller":         "Tech GmbH",
    "buyer":          "Bundesbehörde X",
    "total_amount":   "5950.00",
    "currency":       "EUR"
  }
}

Beispiel 2: Fehlerhafte Rechnung mit Korrekturvorschlag

{
  "tool": "validate_invoice",
  "arguments": {
    "file_content": "JVBERi0xLjQK...",
    "file_type":   "pdf"
  }
}

{
  "valid":   false,
  "format":  "ZUGFeRD 2.4 / Factur-X 1.0",
  "profile": "EN16931",
  "summary": "1 Fehler gefunden",
  "errors": [{
    "severity":       "error",
    "rule_id":        "BR-DE-23",
    "field":          "BT-10",
    "message":        "Käuferreferenz (BT-10) muss für XRechnung angegeben werden.",
    "fix_suggestion": "Füge 'ram:BuyerReference' hinzu, z.B. '04011000-1234-34' für Behörden.",
    "xpath":          "//ram:ApplicableHeaderTradeAgreement/ram:BuyerReference"
  }],
  "warnings": []
}

Beispiel 3: XML extrahieren und validieren

// Schritt 1 — XML aus PDF extrahieren
{ "tool": "extract_xml", "arguments": { "pdf_content": "JVBERi0x..." } }

// Schritt 2 — Extrahiertes XML validieren (base64-kodiert übergeben)
{ "tool": "validate_invoice", "arguments": { "file_content": "<base64 des xml_content>", "file_type": "xml" } }

Beispiel 4: Konsistenzprüfung

{
  "tool": "check_consistency",
  "arguments": { "pdf_content": "JVBERi0xLjQK..." }
}

{
  "consistent":    false,
  "discrepancies": [{
    "field":     "total_amount",
    "pdf_value": "1190.00",
    "xml_value": "1180.00",
    "message":   "Gesamtbetrag im PDF ('1190.00') unterscheidet sich von dem im XML ('1180.00')."
  }]
}

11. Grenzen & Bekannte Einschränkungen