E-Rechnung per API und KI-Agent erstellen: finismas MCP-Server

1. Warum eine API für E-Rechnungen?

Die E-Rechnungspflicht macht aus der Rechnung ein strukturiertes Datenformat. Wo Rechnungen ohnehin maschinell entstehen, im Faktura-Skript, im CRM, im Abrechnungslauf am Monatsende, ist der Umweg über eine Weboberfläche ein Medienbruch. Die naheliegende Lösung: Das System, das die Rechnungsdaten schon hat, ruft eine E-Rechnung-API auf und bekommt die fertige ZUGFeRD-Datei zurück.

Dazu kommt eine neue Nutzergruppe: KI-Agenten. Sie können Rechnungsdaten aus E-Mails, Verträgen oder Zurufen zusammentragen, aber sie können keine normkonforme E-Rechnung ausgeben. Ein Sprachmodell schreibt plausibles XML, kein gültiges. Was fehlt, ist ein Werkzeug, das der Agent aufrufen kann und das die Normarbeit zuverlässig übernimmt. Genau dafür gibt es das Model Context Protocol.

2. Drei Wege zu finisma: Web, MCP, WebMCP

Unter der Haube nutzt alles dieselbe Funktionsschicht, nur der Zugang unterscheidet sich:

Das maschinenlesbare Verzeichnis aller Tools inklusive JSON-Schemas liegt unter finisma.de/api/capabilities. Ein Agent, der die Seite nur liest, findet die Zugänge außerdem in der llms.txt.

Die vollständige Referenz zu allen vier Kanälen (REST, MCP, WebMCP, OAuth) mit Auth-Optionen, Feldern und Fehlerformaten steht in der Entwickler-Dokumentation.

3. Die Tools: prüfen gratis, erzeugen im Abo

Wichtig für Kostenkontrolle und Verlässlichkeit: create_zugferd arbeitet ohne Sprachmodell. Die Erzeugung ist deterministisch, dieselbe Eingabe liefert dieselbe Rechnung. Der kreative Teil bleibt beim Agenten, die Norm bleibt bei finisma.

4. So sieht ein Aufruf aus

Der MCP-Server spricht JSON-RPC über HTTP (Streamable-HTTP-Transport). Dateien reisen Base64-kodiert im JSON. Ein Erzeugungs-Aufruf, auf das Wesentliche gekürzt:

curl -X POST https://finisma.de/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fnsm_IHR_KEY" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
      "name": "create_zugferd",
      "arguments": {
        "pdf_base64": "<Rechnungs-PDF als Base64>",
        "invoice": {
          "invoiceNumber": "RE-2026-042",
          "issueDate": "2026-07-08",
          "seller": { "name": "…", "vatId": "DE…", "address": { … } },
          "buyer":  { "name": "…", "address": { … } },
          "lines": [ { "name": "Beratung", "quantity": 10,
                       "unitPriceNet": 100, "vatRatePercent": 19,
                       "lineNetAmount": 1000 } ],
          "vatBreakdown": [ { "ratePercent": 19, "basisAmount": 1000,
                              "taxAmount": 190 } ],
          "totalNet": 1000, "totalVat": 190, "totalGross": 1190
        }
      }
    }
  }'

Die Antwort enthält die fertige ZUGFeRD-PDF Base64-kodiert im Feld pdf_base64. Wer das Ergebnis gegenprüfen will, schickt es direkt an verify_zugferd zurück: Struktur, EN-16931 und PDF/A-3 werden dann unabhängig validiert. MCP-Clients wie Claude bauen diese Aufrufe selbst zusammen; das JSON-Schema der Rechnungsdaten liefert der Server beim Tool-Listing gleich mit.

Fakturieren Sie über die API an einen öffentlichen Auftraggeber, geben Sie zusätzlich buyerReference mit. Dort erwartet finisma die Leitweg-ID und schreibt sie normkonform in BT-10 der Rechnung. Aufbau und Herkunft der Leitweg-ID erklärt der Artikel Leitweg-ID in der E-Rechnung.

pdf_base64 passt für Skripte, n8n-Workflows und eigene Backends, die die PDF-Bytes bereits vorliegen haben. Für n8n gibt es inzwischen eine eigene Schritt-für-Schritt-Anleitung: E-Rechnungen automatisch mit n8n erzeugen. Wer statt JSON-RPC lieber direkt HTTP spricht, findet dieselben Funktionen als REST-API-Referenz. Eine im Chat angehängte Datei kann ein Modell dagegen nicht zuverlässig als Base64 in einen Tool-Aufruf schreiben, nach dem Anhängen hat es keinen Zugriff mehr auf die exakten Bytes. Für Claude und ChatGPT gibt es dafür den Fallback über request_upload_link, siehe Abschnitt 6.

5. In vier Schritten einsatzbereit

6. KI-Agenten anbinden: Claude, ChatGPT, Browser

Claude und andere MCP-Clients bekommen den Server als Connector: URL https://finisma.de/api/mcp, Authentifizierung per Bearer-Token mit dem API-Key. Danach stehen beide Tools im Gespräch zur Verfügung. Der Agent sammelt die Rechnungsdaten, ruft create_zugferd auf und reicht die fertige Datei weiter.

ChatGPT unterstützt MCP-Server ebenfalls als Connector. Der Ablauf ist derselbe: Rechnung im Chat diktieren, der Agent strukturiert die Daten, finisma baut und prüft die ZUGFeRD-Datei. Die ausführliche Schritt-für-Schritt-Anleitung dazu steht im Artikel E-Rechnung mit ChatGPT erstellen.

Angehängte Dateien im Chat: Hängen Sie die Rechnung als PDF direkt im Chat an, kann das Modell sie nicht einfach als Base64 an ein Tool weiterreichen, die Datei wird beim Anhängen tokenisiert und die exakten Bytes sind danach nicht mehr verlustfrei abrufbar. Für genau diesen Fall gibt es das Tool request_upload_link: Es liefert einen kurzlebigen Link, über den Sie die PDF ganz normal im Browser hochladen. Der Agent bekommt danach nur eine kurze upload_id und übergibt sie statt pdf_base64 an create_zugferd oder verify_zugferd. Die fertige ZUGFeRD-Rechnung kommt in diesem Fall als Download-Link zurück statt als eingebetteter Base64-Block.

Direkt-Upload ohne Browser-Schritt: Seit August 2026 nennt die Antwort von request_upload_link zusätzlich eine upload_api_url. Ein Agent, der selbst HTTP sprechen darf (Shell mit Netzzugriff), lädt die Datei damit ohne menschlichen Klick hoch:

curl -sS -X POST \
  -F "file=@rechnung.pdf;type=application/pdf" \
  "<upload_api_url aus der Tool-Antwort>"

Randbedingungen: Multipart-Feld file, nur echte PDFs, max. 25 MB, der Slot verfällt 20 Minuten nach request_upload_link. Voraussetzung ist, dass der Client finisma.de erreichen darf — in Claude-Umgebungen mit Netz-Sandbox heißt das, die Domain in die Domain-Allowlist der Umgebung aufzunehmen. Ohne diesen Netzzugriff bleibt der Browser-Weg über upload_url.

Browser-Agenten müssen den Umweg über den Remote-Server nicht gehen: finisma.de deklariert seine Tools zusätzlich in der Seite selbst, über den entstehenden WebMCP-Standard (document.modelContext). Ein Agent, der im Browser eines eingeloggten Abonnenten arbeitet, ruft die Tools direkt in der laufenden Session auf, ganz ohne API-Key.

7. Datenschutz und Grenzen

• Keine Speicherung: MCP-Aufrufe werden im Speicher verarbeitet. PDF rein, ZUGFeRD raus, danach ist nichts mehr da. Das passt zur übrigen Plattform, auf der hochgeladene Dateien nach 5 Minuten gelöscht werden.
• API-Keys als Hash: finisma speichert Keys nur als SHA-256-Hash. Ein Key wird genau einmal angezeigt und lässt sich im Konto jederzeit sofort widerrufen.
• Größen: bis 25 MB pro PDF, bis 10 MB pro Anhang, Base64-kodiert im JSON.
• Rate-Limits: 30 Prüfungen und 20 Erzeugungen pro Minute je Key beziehungsweise Aufrufer.

Und wer gar nicht automatisieren will: Für einzelne Rechnungen bleibt der Weg über die Website der einfachste. Dort können Sie kostenlos PDF in E-Rechnung umwandeln, ohne Konto und ohne Key. Warum das Thema ohnehin jeden trifft, zeigt der Überblick zur E-Rechnungspflicht ab 2027.

8. Häufige Fragen zur E-Rechnung-API

Die wichtigsten Antworten kompakt, für alle, die schnell eine Einschätzung brauchen.

Quellen und weiterführende Informationen

• Model Context Protocol: offizielle Spezifikation und Dokumentation
• W3C Web Machine Learning: WebMCP (Web Model Context API), Entwurf
• Forum elektronische Rechnung Deutschland (FeRD): ZUGFeRD-Spezifikation
• EN 16931-1: Semantisches Datenmodell der elektronischen Rechnung