# German E-Rechnung MCP Server (`mcp-server-erechnung`)

Official **Model Context Protocol (MCP)** server for German B2B & B2G E-Invoicing compliance (**EN 16931 / Wachstumschancengesetz 2025–2027**, **KoSIT XRechnung 3.0.2**, **DATEV ZUGFeRD 2.5 / Factur-X PDF/A-3b**, **SEPA GiroCode QR**, and **Smart Hybrid Parsing**).

Connect **Claude Desktop**, **Claude Code**, **Cursor**, **Windsurf**, **Cline**, or **n8n AI Agents** to deterministic German E-Rechnung generation, official KoSIT/veraPDF validation, and guarded Empfangspflicht parsing — with **zero silent LLM hallucinations** in tax or monetary fields.

---

## Why Use This MCP Server?

- **100% Deterministic Financial Math (`BigDecimal` + ISO 13616 `MOD-97`):** Your AI agent never generates raw XML and never computes final invoice math. Every `qty * unitPriceNet`, VAT bucket, and `grossTotal` is calculated deterministically in exact decimal arithmetic, and every Seller IBAN is verified via Modulo-97.
- **DATEV & KoSIT XRechnung 3.0 Compliant (`BR-DE-*` + `veraPDF`):** Enforces German Business Rules (`SellerContact`, `Leitweg-ID` / `BT-10`, SEPA `BG-16`), embeds TrueType fonts + `sRGB` ICC profiles (`ISO 19005-3 PDF/A-3b`), and stamps scannable German **GiroCode (EPC SEPA QR)** payment codes.
- **Smart Developer DX:** Automatically maps human units (`"Stk"`, `"Std"`, `"Tage"`, `"pauschal"`, `"kg"`, `"kWh"`) to UN/ECE Rec 20 codes (`C62`, `HUR`, `DAY`, `LS`, `KGM`, `KWH`) and auto-infers `0%` VAT categories (`AE` § 13b Reverse Charge, `K` § 6a Intra-EU, `E` § 19 UStG, `G` Export) with mandatory `BT-120` German exemption text.
- **100% Stateless & GDPR / DSGVO Safe:** Zero invoice persistence or PII logging.

---

## Available MCP Tools

| Tool Name | Description |
| :--- | :--- |
| `generate_erechnung` | Deterministically generate a `ZUGFeRD 2.5` `PDF/A-3b` (with visual DIN 5008 layout + GiroCode QR + `factur-x.xml`) or pure `XRechnung 3.0.2` XML from structured JSON (`<300ms`). |
| `validate_erechnung` | Validate any ZUGFeRD PDF or XRechnung XML against official EN 16931 XSD, KoSIT `XR_30` Schematron, and `veraPDF` (`rule_id`, `field`, `human_hint`). |
| `parse_erechnung` | Smart Hybrid *Empfangspflicht* parser: `~20ms` deterministic `NATIVE_XML` fast-path first, plus math-guarded legacy PDF extraction (`math_verified`, `iban_valid`, `discrepancy`). |
| `embed_zugferd_pdf` | Upgrade an existing visual PDF (Base64) + JSON into a true `PDF/A-3b` ZUGFeRD 2.5 hybrid document. |
| `magic_convert_pdf` | Convert a flat legacy PDF (Base64, max 5 pages) into ZUGFeRD 2.5 `PDF/A-3b` under strict `BigDecimal` & `MOD-97` guardrails. |

---

## Quickstart

### 1. Get an API Key (Free Tier Available)
Subscribe to the **German E-Rechnung ZUGFeRD & XRechnung API** on RapidAPI Hub:
https://rapidapi.com/flamegoalhunter/api/german-e-rechnung-zugferd-and-xrechnung

### 2. Option A — Local `npx` (`stdio`) for Claude Desktop / Cursor / Windsurf

Add to your `claude_desktop_config.json` or `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "german-erechnung": {
      "command": "npx",
      "args": ["-y", "mcp-server-erechnung"],
      "env": {
        "ERECHNUNG_RAPIDAPI_KEY": "YOUR_RAPIDAPI_KEY"
      }
    }
  }
}
```

### 3. Option B — Zero-Install Remote Streamable HTTP MCP

Connect any Streamable HTTP MCP client directly without `npx`:

- **URL:** `https://german-e-rechnung-zugferd-and-xrechnung.p.rapidapi.com/api/v1/mcp`
- **Headers:**
  - `X-RapidAPI-Key: YOUR_RAPIDAPI_KEY`
  - `X-RapidAPI-Host: german-e-rechnung-zugferd-and-xrechnung.p.rapidapi.com`

---

## License

MIT © FGH Studio