Buchhaltung mit Claude Code und dem epago-MCP-Server

Überblick

Mit dem epago-MCP-Server kann ein KI-Agent, zum Beispiel Claude Code, in deiner epago-Buchhaltung arbeiten: Belege ablegen, Eingangsrechnungen buchen, Ausgangsrechnungen anlegen und Zahlungen erfassen. Der Agent nutzt dabei dieselbe Schnittstelle (Public API v1) und dieselben Prüfungen wie jedes andere Programm mit einem API-Schlüssel. Es gibt keinen zweiten, laxeren Weg: Soll gleich Haben, Periodensperre und GoBD-Unveränderbarkeit gelten für den Agenten genauso wie für dich in der Oberfläche.

Dieser Artikel zeigt, was in einem Testlauf mit einem Agenten tatsächlich funktioniert hat, und nennt genauso deutlich, was der Agent nicht bucht. Zugesagt ist nur, was unter Was der Agent bucht steht.

Version: Die hier beschriebenen Werkzeugbeschreibungen (unbezahlte Eingangsrechnung melden, Beleg ablegen mit Dublettenerkennung) gelten ab Version 0.5.1 des MCP-Servers.

Einrichtung

1. Schlüssel anlegen. Unter Mein Konto → API-Schlüssel legst du einen Schlüssel mit den Rechten Lesen und Schreiben an. Ohne write sieht der Agent die Schreib-Werkzeuge gar nicht. Wie das geht, steht in Mein Konto: Profil, Team und API-Schlüssel.
2. Erst in der Sandbox. Fang mit einem Sandbox-Schlüssel (epago_test_…) an. Er erreicht nur den Testmandanten, nie deine echte Buchhaltung. Eine Testbuchung ist trotzdem eine richtige Buchung und nach GoBD unveränderbar.
3. Server einbinden. Den Quelltext und die Konfiguration findest du unter epago.de/entwickler/mcp. Der MCP-Client startet den Server als Prozess mit zwei Umgebungsvariablen, EPAGO_API_KEY und optional EPAGO_API_URL.
4. Prüfen. Beim Start meldet der Server Umgebung: SANDBOX oder LIVE. Der Agent kann dasselbe mit dem Werkzeug mandant_info abfragen.

Ein Beispielauftrag

Du schreibst dem Agenten zum Beispiel:

Leg die Belege im Ordner oktober ab. Bezahlte Eingangsrechnungen buchst du, unbezahlte meldest du mir. Danach legst du die Rechnung an Beispiel Kunde GmbH über 2.000,00 EUR netto an und buchst sie.

Was der Agent daraus macht, steht in den nächsten Abschnitten. Wichtig ist der Ablauf: Er legt jeden Beleg zuerst ab, fragt bei Unklarheiten nach (Wurde die Rechnung schon bezahlt? Womit?) und zeigt dir den Buchungssatz, bevor er bucht.

Was der Agent bucht

Bezahlte Eingangsrechnung mit 19 % Vorsteuer

Ein inländischer Lieferant, ein Steuersatz, bezahlt per Bank oder Kasse. Der Agent bucht mit Steuerschlüssel 9 gegen das Geldkonto, in einem Aufruf, mit einer Aufwands- und einer Vorsteuerzeile.

Beispiel Bürobedarf, 119,00 EUR brutto, per Bank bezahlt:

Bezahlte Eingangsrechnung mit 7 % Vorsteuer

Genauso, mit Steuerschlüssel 8. Beispiel Fachliteratur, 85,60 EUR brutto, per Bank bezahlt:

Die Belegnummer des Lieferanten übernimmt der Agent als Referenz der Buchung. Eine Verknüpfung der Buchung mit dem abgelegten Beleg gibt es über diese Schnittstelle nicht (siehe unten).

Ausgangsrechnung anlegen, buchen und voll bezahlt erfassen

Der Agent legt die Rechnung an, bucht sie und erfasst die Zahlung. Bei 1.000,00 EUR netto und 19 % Umsatzsteuer entsteht:

Die Zahlung über 1.190,00 EUR gleicht die Forderung aus. Die Zahlungsantwort meldet den Beleg danach als ausgeglichen.

Teilzahlung und Skonto auf den Rest

Bei einer Rechnung über 2.380,00 EUR brutto (2.000,00 netto) kommt zuerst eine Teilzahlung über 1.000,00 EUR, danach die Zahlung des Rests abzüglich 2 % Skonto (1.332,40 EUR bei 47,60 EUR Abzug). Dabei gilt:

• epago fragt die Zahlungsart ab, der Agent rät sie nicht. Ohne Angabe antwortet die Schnittstelle mit zahlungsart_erforderlich, nennt den offenen Rest und die Optionen. Der Agent fragt dich dann.
• Ein Skonto braucht eine Begründung, solange an der Rechnung keine Skontobedingungen stehen. Das ist eine Regel von epago: so bleibt nachvollziehbar, warum das Entgelt gemindert wurde.
• Das Skonto wird gebucht und die Steuer berichtigt. Der Abzug von 47,60 EUR brutto trennt sich in 40,00 EUR Erlösminderung und 7,60 EUR Umsatzsteuer:

Die Antwort auf die Skonto-Zahlung sagt, was passiert ist: entgeltminderung.art ist ausgeglichen, offenerRest ist 0, dazu kommen minderungBetrag, belegAusgeglichen und eine Meldung. Der Agent muss also nichts mehr nachbuchen. Die Forderung steht danach auf 0,00 EUR.

Fehlt ein Konto wie 8736 oder 4736 in deinem Kontenplan, übernimmt epago es beim Buchen aus dem DATEV-Kontenrahmen. Du musst es nicht vorher anlegen.

Was der Agent meldet

Zwei Dinge bucht der Agent absichtlich nicht, sondern legt sie ab und meldet sie dir als offene Aufgabe.

• Unbezahlte Eingangsrechnungen. Der Agent legt den Beleg ab und meldet dir Lieferant, Rechnungsnummer, Betrag und Fälligkeit. Er bucht keine Verbindlichkeit, weil sich eine Eingangsrechnung über diese Schnittstelle nicht als offener Posten anlegen lässt und eine frei gebuchte Verbindlichkeit niemand überwachen würde.
• Unlesbare Belege, zum Beispiel ein abgeschnittener Scan. Der Beleg bleibt abgelegt, gebucht wird nichts.

Das hat eine Folge für die Umsatzsteuer: Die Vorsteuer aus einer unbezahlten, nur gemeldeten Eingangsrechnung steht erst in der Voranmeldung, wenn du sie gebucht hast. Nach § 15 Abs. 1 Satz 1 Nr. 1 UStG ist sie abziehbar, sobald die Leistung ausgeführt ist und dir die Rechnung vorliegt. Behalte die gemeldeten Aufgaben deshalb im Blick, bevor du die Voranmeldung abgibst.

Belege ablegen

Der Agent legt Belege als PDF, Bild oder Tabelle ab, bis rund 3 MB je Datei (Base64 vergrößert die Datei, und eine Anfrage darf höchstens 4,5 MB groß sein). Größere Belege lädst du in der Oberfläche hoch. Zwei Eigenschaften:

• Dubletten werden erkannt. Legt der Agent dieselbe Datei noch einmal ab, antwortet epago mit 409 beleg_dublette und nennt die vorhandene Beleg-ID. Es entsteht kein zweiter Beleg.
• Der Upload liest den Beleg nicht. Es gibt keine Texterkennung über diese Schnittstelle. Den Inhalt (Betrag, Steuersatz, Lieferant) muss der Agent selbst aus der Datei lesen.

Was der Agent nicht bucht

• Unbezahlte Eingangsrechnungen bucht der Agent nicht, er meldet sie als Aufgabe (siehe oben).
• Bankumsätze kann der Agent weder lesen noch zuordnen, weil die Schnittstelle kein Werkzeug dafür hat. Zahlungen ohne Beleg erfasst du in der Oberfläche unter Umsätze zuordnen.
• Reverse Charge (zum Beispiel eine Software-Rechnung aus Irland nach § 13b UStG) gehört nicht zum zugesagten Umfang. Die vereinfachte Buchung baut die Zeilen für die Steuerschuld des Leistungsempfängers nicht selbst, der Agent müsste die Steuerkonten kennen und alle Zeilen einzeln angeben.
• Bewirtung gehört ebenfalls nicht dazu. Mit zwei Steuersätzen, Trinkgeld und der 70/30-Aufteilung wäre es eine freie Buchung, deren Aufteilung der Agent rechnet und epago nicht prüft.
• Eigenbeleg für Ausgaben ohne Rechnung bucht der Agent nicht. Den Eigenbeleg erfasst du selbst.
• Verknüpfung von Beleg und Buchung gibt es über die Schnittstelle nicht. Der Agent übernimmt die Belegnummer als Referenz der Buchung, die Zuordnung zum abgelegten Beleg machst du in der Oberfläche, siehe Belege hochladen und zuordnen.

Wo epago prüft und abweist

Die Prüfungen laufen in epago, nicht im Agenten. Du musst dich nicht darauf verlassen, dass der Agent alles richtig rechnet:

• Soll gleich Haben auf den Cent. Eine unausgeglichene Buchung wird abgewiesen.
• Steuer ohne Schlüssel: Eine Vorsteuerzeile ohne Steuerschlüssel wird gegen eine Obergrenze geprüft. Ist die Steuer höher, als sie zum Aufwand derselben Seite bei dem Satz des Kontos sein könnte, antwortet epago mit 400 und nennt den möglichen Höchstbetrag und den Ausweg (Schlüssel setzen oder Betrag prüfen). Unter der Grenze wird die Buchung angenommen. Die Kennzahlen der Voranmeldung hängen trotzdem am Steuerschlüssel, deshalb verlangt die Werkzeugbeschreibung ihn.
• Fehlende Konten: Steht ein Konto weder in deinem Kontenplan noch unter den Konten der Steuerfälle, nennt die Fehlermeldung, ob es im Kontenrahmen bereitsteht. Übernehmen kannst du es in der Oberfläche, der Agent kann es nicht.
• Periodensperre und GoBD: In festgeschriebenen Perioden bucht niemand mehr, gebuchte Sätze bleiben unveränderlich, Korrekturen laufen über einen Storno mit dem Datum des Tages.
• Zahlungsart und Begründung bei Teilzahlung, Skonto und Forderungsausfall (siehe oben).
• Doppelte Rechnungen: Mit einem idempotenzSchluessel lässt sich das Anlegen einer Rechnung gefahrlos wiederholen. Es entsteht keine zweite Rechnung.

Prüfe das Ergebnis

Lass dir nach dem Lauf die Buchungen zeigen (buchungen_liste) und die Voranmeldung für den Zeitraum (bericht_ustva). In einem Testlauf mit den Beispielen aus diesem Artikel stimmte die Zahllast der Voranmeldung auf den Cent mit der Handrechnung überein. Das ersetzt nicht deine eigene Durchsicht: Die Verantwortung für die Buchhaltung bleibt bei dir, der Agent arbeitet dir zu.

Siehe auch

• Mein Konto: Profil, Team und API-Schlüssel - Schlüssel, Sandbox, Rechte
• Belege hochladen und zuordnen - der Weg in der Oberfläche
• Aufgaben und Datenqualität - Hinweise auf offene Punkte
• Vorsteuer im Glossar - wann Vorsteuer abziehbar ist
• Skonto im Glossar - Zahlungsnachlass und Umsatzsteuer
• GoBD im Glossar - warum Gebuchtes unveränderlich ist