ZUGFeRD / XRechnung
MCP Validation Server

1. Overview

The server provides three tools and one resource that AI agents can call through the Model Context Protocol.

2. Architecture & Data Flow

Flow for validate_invoice

3. Validation Engines

Every request is checked by two engines at once. The results are consolidated, deduplicated and returned.

4. Installation & Configuration

# Register for free:
https://zugferd-validator.de/portal

npm install -g zugferd-mcp-client

// mcp_config.json (path varies by client)
{
  "mcpServers": {
    "zugferd": {
      "command": "zugferd-mcp-client",
      "env": {
        "ZUGFERD_API_KEY": "zv_your_key_here"
      }
    }
  }
}

Direct REST API

The API can also be called directly, without the MCP client:

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

Environment variables (MCP client)

5. Tools

{
  "valid":    true,
  "format":   "ZUGFeRD 2.x",
  "profile":  "EN16931",
  "summary":  "No issues found",
  "errors":   [],
  "warnings": [],
  "notices":  [],
  "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.x",
  "profile": "EN16931",
  "summary": "2 errors, 1 warning found",
  "errors": [
    {
      "severity":       "error",
      "rule_id":        "BR-DE-15",
      "field":          "BT-10",
      "message":        "The buyer reference / routing ID (BT-10) must be provided.",
      "fix_suggestion": "Add the buyer reference / routing ID (BT-10) in 'ram:ApplicableHeaderTradeAgreement/ram:BuyerReference'.",
      "xpath":          "//ram:ApplicableHeaderTradeAgreement/ram:BuyerReference"
    }
  ],
  "warnings": [
    {
      "severity":       "warning",
      "rule_id":        "BR-CL-10",
      "field":          "BT-81",
      "message":        "The payment means code must come from UNTDID 4461.",
      "fix_suggestion": "Use e.g. '58' for SEPA credit transfer or '59' for SEPA direct debit.",
      "xpath":          "//ram:SpecifiedTradeSettlementPaymentMeans/ram:TypeCode"
    }
  ]
}

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

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

{
  "consistent":    false,
  "discrepancies": [
    {
      "field":     "total_amount",
      "pdf_value": "1190.00",
      "xml_value": "1180.00",
      "message":   "The total amount in the PDF ('1190.00') differs from the one in the XML ('1180.00')."
    }
  ]
}

{
  "format":     "zugferd",
  "profile":    "EN16931",
  "pdf_base64": "JVBERi0xLjc…",
  "xml":        "<?xml version=\"1.0\"…",
  "branding":   "free_footer"
}

6. Resource: validation_rules

Returns the server's current rule set: supported formats, profiles and the validation engine in use.

URI: validation://rules

{
  "supported_formats": [
    "ZUGFeRD 1.0", "ZUGFeRD 2.0", "ZUGFeRD 2.1", "ZUGFeRD 2.2",
    "ZUGFeRD 2.3", "ZUGFeRD 2.x / Factur-X 1.0x",
    "XRechnung 1.2", "XRechnung 2.0", "XRechnung 2.3", "XRechnung 3.0"
  ],
  "supported_profiles": [
    "minimum", "basic_wl", "basic", "en16931", "extended", "xrechnung"
  ],
  "validation_engines": [
    "Mustang Project v2.22.0",
    "KoSIT Validierungstool v1.6.2 (XRechnung 3.0.2 + EN 16931 CII)"
  ],
  "last_updated":      "2026-04-08"
}

7. Error Handling

On failure, all tools return a JSON object with an error field. There is never unstructured error output.

{
  "error":   "Short error category",
  "details": "Detailed description with a concrete hint on how to fix it."
}

8. Common Data Types

ValidationIssue

Used in the errors, warnings and notices arrays of validate_invoice.

InvoiceMetadata

Optional field in the result of validate_invoice (only for file_type: "xml").

9. Supported Formats & Profiles

Formats

Profiles (ZUGFeRD/Factur-X)

10. Rule Set & Fix Suggestions

The server contains a database of fix suggestions for 63 rule categories. Errors from both validation engines (Mustang + KoSIT) are consolidated — when a known rule ID is found, the fix suggestion is attached automatically.

11. Usage Examples

Example 1: Validate an XRechnung XML

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

{
  "valid":   true,
  "format":  "XRechnung 3.0",
  "profile": "XRECHNUNG",
  "summary": "No issues found",
  "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"
  }
}

Example 2: Faulty invoice with a fix suggestion

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

{
  "valid":   false,
  "format":  "ZUGFeRD 2.x",
  "profile": "EN16931",
  "summary": "1 error found",
  "errors": [{
    "severity":       "error",
    "rule_id":        "BR-DE-23",
    "field":          "BT-10",
    "message":        "The buyer reference (BT-10) must be provided for XRechnung.",
    "fix_suggestion": "Add 'ram:BuyerReference', e.g. '04011000-1234-34' for public authorities.",
    "xpath":          "//ram:ApplicableHeaderTradeAgreement/ram:BuyerReference"
  }],
  "warnings": []
}

Example 3: Extract and validate XML

// Step 1 — extract the XML from the PDF
{ "tool": "extract_xml", "arguments": { "pdf_content": "JVBERi0x..." } }

// Step 2 — validate the extracted XML (passed Base64-encoded)
{ "tool": "validate_invoice", "arguments": { "file_content": "<base64 of xml_content>", "file_type": "xml" } }

Example 4: Consistency check

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

{
  "consistent":    false,
  "discrepancies": [{
    "field":     "total_amount",
    "pdf_value": "1190.00",
    "xml_value": "1180.00",
    "message":   "The total amount in the PDF ('1190.00') differs from the one in the XML ('1180.00')."
  }]
}

12. Limits & Known Constraints

13. Changelog