MCP-Server für XRechnung und ZUGFeRD

Adresse und Paket

Der Server läuft gehostet unter dieser Adresse (Streamable HTTP) und als npm-Paket für Clients, die Server als lokalen Prozess starten (stdio). Beide bieten dieselben Werkzeuge.

Gehostet

https://normapi.com/mcp

Lokal (stdio)

npx -y @normapi/mcp

Verbinden

In Clients mit Konnektoren genügt die Adresse; beim ersten Erzeugen einer Rechnung meldet der Client Sie über OAuth bei NormAPI an. Clients mit Konfigurationsdatei nehmen alternativ Ihren API-Schlüssel als Header.

Claude (claude.ai und Desktop): Einstellungen → Konnektoren → Eigenen Konnektor hinzufügen, Adresse einfügen.
ChatGPT: im Entwicklermodus einen eigenen Konnektor mit dieser Adresse anlegen, Authentifizierung OAuth.

Claude Code

claude mcp add --transport http normapi https://normapi.com/mcp

# or with your key instead of OAuth:
claude mcp add --transport http normapi https://normapi.com/mcp \
  --header "Authorization: Bearer nk_live_…"

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "normapi": {
      "url": "https://normapi.com/mcp",
      "headers": { "Authorization": "Bearer nk_live_…" }
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "normapi": { "type": "http", "url": "https://normapi.com/mcp" }
  }
}

Jeder Client mit stdio (z. B. claude_desktop_config.json)

{
  "mcpServers": {
    "normapi": {
      "command": "npx",
      "args": ["-y", "@normapi/mcp"],
      "env": { "NORMAPI_API_KEY": "nk_live_…" }
    }
  }
}

Werkzeuge

Drei Werkzeuge, jedes mit strukturiertem Ergebnis und einer Textfassung für Modelle, die nur Text lesen.

Werkzeug	Was es tut	Konto
`validate_invoice`	Prüft eine XRechnung (UBL oder CII, als Text) oder ein ZUGFeRD-/Factur-X-PDF (base64) gegen das offizielle KoSIT-Regelwerk. Liefert das Urteil, die Regelwerksversion und jeden Befund; jeder Geschäftsregel-Befund mit Erklärung: was die Regel verlangt, warum sie typischerweise auslöst, wie man es behebt.	nein
`generate_invoice`	Erzeugt aus Rechnungsdaten eine XRechnung (UBL oder CII) oder ein ZUGFeRD-PDF. Summen werden serverseitig dezimal berechnet, das Dokument wird vor der Rückgabe validiert. Daten, die das Regelwerk nicht zulässt, werden mit den verletzten Regeln und ihrer Behebung abgelehnt — ohne Anrechnung.	ja, zählt gegen das Kontingent
`explain_rule`	Erklärt eine Regel per Code (BR-DE-15, BR-CO-10, PEPPOL-EN16931-R010 …), mit Link zur ausführlichen Seite.	nein

Anmeldung und Schlüssel

Drei Wege, je nach Client:

OAuth 2.1 (Claude, ChatGPT und andere Konnektoren): Sie melden sich bei NormAPI an und erlauben die Verbindung. Sie erhält einen eigenen API-Schlüssel, benannt nach der App (mcp-claude-…). Widerrufen Sie ihn unter API-Schlüssel, ist die App sofort getrennt.
API-Schlüssel als Header (Claude Code, Cursor, VS Code): Authorization: Bearer nk_live_… — derselbe Schlüssel wie für die REST-API.
stdio: der Schlüssel als Umgebungsvariable NORMAPI_API_KEY.

API-Schlüssel anlegen

Grenzen und Datenschutz

Dieselben Regeln wie für die REST-API:

Dokumente bis 5 MB. Anfragen ohne Schlüssel unterliegen den anonymen Grenzen der API, mit Schlüssel denen Ihres Schlüssels.
Jede erzeugte Rechnung zählt gegen das Monatskontingent (25 frei); Prüfen nie.
Rechnungen werden im Speicher verarbeitet und nicht gespeichert — auch nicht vom MCP-Server.
Technische Prüfung, keine Steuer- oder Rechtsberatung.

Zur API-Dokumentation