# E-Invoice MCP Server

> MCP Server fuer E-Rechnungen im DACH-Raum — XRechnung erstellen, validieren und Daten extrahieren. Direkt aus Claude, Cursor oder jedem MCP-Client.

[![npm version](https://img.shields.io/npm/v/einvoice-mcp.svg)](https://www.npmjs.com/package/einvoice-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

## Was ist das?

E-Invoice MCP ist ein [Model Context Protocol](https://modelcontextprotocol.io/) Server fuer die Erstellung und Validierung von E-Rechnungen nach dem deutschen XRechnung-Standard. Ab 2027 muessen alle Unternehmen in Deutschland E-Rechnungen versenden koennen — mit diesem Tool bist du vorbereitet.

Du sagst Claude einfach: "Erstelle eine Rechnung an die Beispiel GmbH fuer 10 Stunden Beratung" — und erhaeltst eine valide XRechnung als UBL 2.1 XML.

## Features

- **XRechnung erstellen** — Valides UBL 2.1 XML aus strukturierten Daten (EN 16931 + XRechnung 3.0.2)
- **E-Rechnung validieren** — Syntax, Pflichtfelder und deutsche Business-Regeln (BR-DE) pruefen
- **Daten extrahieren** — Strukturierte Daten aus UBL- oder CII-XML lesen
- **Format-Info** — Nachschlagewerk fuer Pflichtfelder, Steuer-Kategorien, Einheiten-Codes und Fristen
- **Automatische Berechnung** — Netto, Brutto, Steuerbetraege werden automatisch berechnet
- **Plugin-faehig** — Kann standalone laufen ODER in den BuchPilot MCP Server integriert werden
- **Keine externen Dienste** — Alles laeuft lokal, keine API-Keys noetig
- **Keine nativen Abhaengigkeiten** — Laeuft auf jedem System mit Node.js

## Gesetzliche Fristen

| Datum | Was passiert |
|-------|-------------|
| **01.01.2025** | Alle Unternehmen muessen E-Rechnungen **empfangen** koennen |
| **31.12.2026** | PDF-Rechnungen nur noch mit Empfaenger-Zustimmung erlaubt |
| **01.01.2027** | Unternehmen >800.000 EUR Umsatz muessen E-Rechnungen **senden** |
| **01.01.2028** | **ALLE** Unternehmen muessen E-Rechnungen senden |

> Fehlerhafte E-Rechnungen koennen zum Verlust des Vorsteuerabzugs fuehren (+ 6% Verzinsung).

## Installation

### Voraussetzungen

- Node.js >= 18

### npm (global)

```bash
npm install -g einvoice-mcp
```

### Von Source

```bash
git clone https://github.com/makririch/einvoice-mcp.git
cd einvoice-mcp
npm install
npm run build
```

## Konfiguration

Dieser MCP Server benoetigt **keine Konfiguration**. Es werden keine API-Keys oder externe Dienste benoetigt — alles laeuft lokal.

## Nutzung

### Server starten (standalone)

```bash
# Nach npm install -g:
einvoice-mcp

# Oder von Source:
npm start

# Entwicklung mit Auto-Reload:
npm run dev
```

Der Server laeuft ueber stdio und wartet auf MCP-Nachrichten.

### In Claude Desktop verwenden

Siehe [Claude Desktop Setup Guide](docs/claude-desktop-setup.md) fuer eine detaillierte Anleitung.

Kurzversion — fuege in `claude_desktop_config.json` hinzu:

```json
{
  "mcpServers": {
    "einvoice": {
      "command": "npx",
      "args": ["-y", "einvoice-mcp"]
    }
  }
}
```

### Beispiele (natuerliche Sprache in Claude)

Nachdem du den Server konfiguriert hast, kannst du Claude z.B. fragen:

- "Erstelle eine XRechnung an die Beispiel GmbH fuer 10 Stunden Beratung zu 150 EUR"
- "Ist diese XML-Datei eine gueltige XRechnung?"
- "Extrahiere die Rechnungsdaten aus diesem XML"
- "Welche Pflichtfelder brauche ich fuer eine XRechnung?"
- "Welche Steuer-Kategorien gibt es und was bedeuten sie?"
- "Bis wann muss mein Unternehmen E-Rechnungen versenden koennen?"

### Quickstart

Eine Schritt-fuer-Schritt-Anleitung "Erstelle deine erste XRechnung in 5 Minuten" findest du in [docs/quickstart.md](docs/quickstart.md).

## Tool-Referenz

Eine vollstaendige Referenz aller 4 Tools mit Parametern, Beispiel-Inputs und Beispiel-Outputs findest du in [docs/tool-reference.md](docs/tool-reference.md).

### Kurzuebersicht

| Tool | Beschreibung |
|------|-------------|
| `create_xrechnung` | XRechnung (UBL 2.1 XML) aus strukturierten Daten erstellen |
| `validate_invoice` | E-Rechnung XML validieren (Syntax + BR-DE Business-Regeln) |
| `extract_data` | Strukturierte Daten aus UBL- oder CII-XML extrahieren |
| `get_format_info` | Nachschlagewerk fuer Formate, Pflichtfelder, Codes und Fristen |

## BuchPilot-Integration

E-Invoice MCP kann als Plugin in den [BuchPilot MCP Server](https://www.npmjs.com/package/buchpilot-mcp) integriert werden:

```typescript
import { registerEInvoiceTools } from "einvoice-mcp";
registerEInvoiceTools(server);
```

**Kombination:** BuchPilot erstellt eine Rechnung in Lexoffice -> Daten extrahieren -> XRechnung erzeugen -> fertige E-Rechnung.

## Unterstuetzte Standards

| Standard | Version | Status |
|----------|---------|--------|
| XRechnung | 3.0.2 | Erstellen + Validieren |
| EN 16931 | — | Basis fuer XRechnung |
| UBL 2.1 | — | XML-Syntax fuer XRechnung |
| CII (Cross Industry Invoice) | — | Extrahieren (Lesen) |
| ZUGFeRD / Factur-X | 2.3 | Extrahieren (Lesen), Erstellen geplant |

## FAQ / Troubleshooting

### "XML konnte nicht geparst werden"

- Ist das XML well-formed? (Alle Tags korrekt geschlossen?)
- Ist es tatsaechlich eine UBL- oder CII-Rechnung? (Root-Element muss `<Invoice>` oder `<CrossIndustryInvoice>` sein)
- Ist das Encoding UTF-8?

### Validierung zeigt Fehler "BR-DE-13: Buyer Reference ist Pflicht"

Die Kaeufer-Referenz (BT-10) ist in XRechnung Pflicht. Bei Rechnungen an oeffentliche Auftraggeber ist das die **Leitweg-ID**. Bei B2B-Rechnungen kann es eine beliebige Referenz sein (z.B. Bestellnummer).

```json
{
  "buyerReference": "04011000-12345-67"
}
```

### Validierung zeigt Warnung "BR-DE-21: Telefonnummer empfohlen"

Das ist nur eine Warnung, kein Fehler. Die Rechnung ist trotzdem gueltig. Fuer beste Kompatibilitaet solltest du aber eine Telefonnummer des Verkaeufers angeben.

### Welche Steuer-Kategorien gibt es?

| Code | Name | Beschreibung | Steuersaetze |
|------|------|-------------|-------------|
| S | Standard | Normaler Steuersatz | 19%, 7% |
| Z | Nullsatz | 0% (z.B. innergemeinschaftlich mit USt-Befreiung) | 0% |
| E | Steuerbefreit | z.B. Kleinunternehmer nach Paragraph 19 UStG | 0% |
| AE | Reverse Charge | Steuerschuldnerschaft des Empfaengers (Paragraph 13b UStG) | 0% |
| K | Innergemeinschaftlich | Steuerfreie innergemeinschaftliche Lieferung | 0% |

### Welche Einheiten-Codes gibt es?

| Code | Name | Beschreibung |
|------|------|-------------|
| H87 | Stueck | Einzelne Einheit (Default) |
| HUR | Stunde | Arbeitsstunde |
| DAY | Tag | Arbeitstag |
| MON | Monat | Kalendermonat |
| KGM | Kilogramm | Gewicht |
| MTR | Meter | Laenge |
| LTR | Liter | Volumen |
| MTK | Quadratmeter | Flaeche |
| SET | Set/Paket | Zusammenstellung |
| C62 | Einheit (generisch) | Allgemeine Mengeneinheit |

### Server startet, aber Claude erkennt die Tools nicht

- Pruefe ob die `claude_desktop_config.json` korrekt ist
- Starte Claude Desktop neu nach Konfigurationsaenderungen
- Pruefe die Logs: `~/Library/Logs/Claude/mcp.log` (macOS)

## Lizenz

MIT — Frei nutzbar, auch kommerziell.

## Autor

**MaKri** — [GitHub](https://github.com/makririch/einvoice-mcp)