ZUGFeRD / XRechnung
MCP Validation Server

1. Übersicht

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

2. Architektur & Datenfluss

Ablauf für validate_invoice

3. Installation & Konfiguration

npm install

npm run setup

npm run build

MCP-Client-Konfiguration

Claude Desktop

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "zugferd": {
      "command": "node",
      "args": ["/absoluter/pfad/zu/zugferd-mcp-server/dist/index.js"]
    }
  }
}

Docker

docker build -t zugferd-mcp-server .
# In der MCP-Config:
{
  "mcpServers": {
    "zugferd": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "zugferd-mcp-server"]
    }
  }
}

Umgebungsvariablen

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