io.github.makririch/einvoice

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.

Was ist das?

E-Invoice MCP ist ein Model Context Protocol 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)

npm install -g einvoice-mcp

Von Source

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)

# 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 fuer eine detaillierte Anleitung.

Kurzversion — fuege in claude_desktop_config.json hinzu:

{
  "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.

Tool-Referenz

Eine vollstaendige Referenz aller 4 Tools mit Parametern, Beispiel-Inputs und Beispiel-Outputs findest du in 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 integriert werden:

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).

{
  "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