@e-rechnung-inbox/xrechnung-mcp

Model Context Protocol (MCP) server for validating and parsing German e-invoices — XRechnung, ZUGFeRD, and Factur-X.

Stateless. Offline. No API key. Pure local computation over bytes you paste in. Runs via npx, so there's nothing to install permanently.

Built by the team behind e-rechnung-inbox.de — an invite-only B2B inbox for German SMEs and tax advisors that receives, validates, archives, and exports e-invoices to DATEV.

Install (Claude Desktop)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent %APPDATA%\Claude\claude_desktop_config.json on Windows, and add:

{
  "mcpServers": {
    "xrechnung": {
      "command": "npx",
      "args": ["-y", "@e-rechnung-inbox/xrechnung-mcp"]
    }
  }
}

Restart Claude Desktop. The three tools (validate_xrechnung, parse_invoice, extract_zugferd) will show up in any new conversation.

Install (Cursor / generic MCP)

npx -y @e-rechnung-inbox/xrechnung-mcp

The server speaks MCP over stdio. Point any MCP-capable client at it.

Tools

validate_xrechnung(xml)

Structural validation of an XRechnung or ZUGFeRD/Factur-X XML document against the EN 16931 European e-invoice core model.

Input

{ "xml": "<Invoice>...</Invoice>" }

Output (abridged)

{
  "status": "valid" | "warning" | "invalid",
  "score": 95,
  "issueCount": 0,
  "issues": [],
  "parsed": {
    "invoiceNumber": "RE-2026-0042",
    "invoiceDate": "2026-04-23",
    "senderName": "Example GmbH",
    "grossAmount": 1190.00,
    "currency": "EUR",
    "customizationId": "urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0",
    "specificationId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
  }
}

This is the TS+Zod validator we ship in production at e-rechnung-inbox.de. It covers the structural/core-model layer. For reference-implementation parity you'd pair it with the KoSIT Java validator (that's a Stage 2 deployment decision for us — see ADR-013 in the main repo).

parse_invoice(xml)

Parse XRechnung/ZUGFeRD XML into a normalized invoice structure with header fields, totals, line items, and tax breakdown. Useful for data extraction without going through the full validation cycle.

Input

{ "xml": "<Invoice>...</Invoice>" }

Output (abridged)

{
  "parsed": {
    "invoiceNumber": "RE-2026-0042",
    "invoiceDate": "2026-04-23",
    "dueDate": "2026-05-23",
    "senderName": "Example GmbH",
    "senderVatId": "DE123456789",
    "buyerName": "Acme AG",
    "netAmount": 1000,
    "taxAmount": 190,
    "grossAmount": 1190,
    "currency": "EUR",
    "iban": "DE89370400440532013000",
    "taxBreakdown": [{ "taxRate": 19, "taxableAmount": 1000, "taxAmount": 190 }]
  },
  "lineItems": [
    { "description": "Consulting", "quantity": 10, "unitPrice": 100, "taxRate": 19, "lineTotal": 1000 }
  ]
}

extract_zugferd(pdfBase64)

Extract the embedded Factur-X XML from a ZUGFeRD PDF.

Input

{ "pdfBase64": "JVBERi0xLjQKJcfsj6IK..." }

Output

{
  "found": true,
  "xml": "<Invoice>...</Invoice>"
}

If no embedded XML is found (not a ZUGFeRD PDF, or XML stream is Flate-compressed), the tool returns found: false and a short note. The v0.1 extractor is a simple substring scanner — it covers roughly 95% of real-world Factur-X PDFs. A proper PDF walker ships in v0.2.

Usage examples

Once the server is configured, you can ask Claude things like:

• "Here's an XRechnung XML — is it valid?" → Claude calls validate_xrechnung and reports status + issue details.
• "Pull the sender, buyer, and total from this invoice." → Claude calls parse_invoice and answers from the structured output.
• "What's inside this ZUGFeRD PDF?" → Claude reads the file, base64-encodes it, calls extract_zugferd, then validate_xrechnung / parse_invoice on the result.

What this does NOT do

• No KoSIT reference validation. Running the official Java KoSIT validator requires a JVM; that's out of scope for a local stdio MCP server. For KoSIT parity we run a paired Fly.io-hosted daemon in the main product.
• No network calls. Purely local computation. Your XML never leaves your machine.
• No signature / PAdES verification. .p7s signed invoice envelopes will be handled in v0.2.
• No EN 16931 conformance "offiziell KoSIT-konform" claim. This server does structural validation. For a "KoSIT-validated" assertion you need the KoSIT daemon output.

Roadmap

• v0.2 (≈launch+6 weeks): hosted variant with optional API key, proper ZUGFeRD PDF walker, PAdES signature validation.
• v1.0 (≈launch+8 weeks): optional paired KoSIT call via our Fly.io daemon (requires API key), metered usage.

Source

Source lives in the e-rechnung-inbox monorepo under packages/xrechnung-mcp. The underlying parser/validator lives alongside in @e-rechnung-inbox/xrechnung-core, also on npm, if you want to use the logic directly without MCP.

License

MIT.