Epago

MCP-Server (stdio) für epago, die Buchhaltungssoftware für deutsche KMU. Damit kann jeder MCP-fähige Client direkt in deiner epago-Buchhaltung lesen und buchen: Kontenplan, Buchungen, Rechnungen, Kunden, Zahlungen, Belege, BWA und Umsatzsteuer-Voranmeldung.

Der Server ist ein reiner Client der epago Public API v1. Er braucht einen epago-Account und einen API-Schlüssel. Es gibt keinen Direktzugriff auf eine Datenbank, keine gespeicherten Zugangsdaten und keine Lösch-Werkzeuge.

English: MCP server for the German accounting SaaS epago. Requires an epago account and an API key. Tools and messages are in German, because the domain (German tax law, GoBD, DATEV charts of accounts) is.

Voraussetzungen

• Ein epago-Account unter app.epago.de
• Node.js 20 oder neuer
• Ein API-Schlüssel aus epago: Einstellungen → API-Schlüssel (Anleitung: Mein Konto und API-Schlüssel)

Beim Anlegen des Schlüssels wählst du die Berechtigungen:

Scope	Wirkung im MCP-Server
read	Lese-Werkzeuge (Konten, Buchungen, Rechnungen, Berichte)
write	zusätzlich die Schreib-Werkzeuge (Buchung anlegen, Storno, Zahlung, Rechnung, Beleg)

Der Klartext-Schlüssel (epago_…) wird nur einmal angezeigt. Ein Schlüssel gehört genau einem Mandanten und lässt sich in epago jederzeit widerrufen.

Zum Ausprobieren einen Sandbox-Schlüssel nehmen

Neben der echten Buchhaltung hat jedes epago-Konto einen Testmandanten. Er wird unter Einstellungen → API-Schlüssel mit einem Klick angelegt und kommt mit Beispieldaten: Kontenrahmen, Geschäftsjahr, zwei Kunden, ein Lieferant, zwei Ausgangsrechnungen (eine davon bezahlt) und drei Buchungen.

Dort im selben Bereich entsteht dann ein Schlüssel mit dem Präfix epago_test_. Er erreicht ausschließlich den Testmandanten und niemals die echte Buchhaltung: die Trennung hängt am Schlüssel selbst, nicht an einer Einstellung im Client.

Aus dem Testmandanten geht außerdem nichts nach außen — keine E-Mail, kein ELSTER, keine Bankverbindung, keine Zahlung. Eine Testbuchung, die dort entsteht, ist trotzdem eine richtige Buchung: dieselben GoBD-Regeln, dieselbe Unveränderbarkeit. Wer neu anfangen will, setzt den Testmandanten zurück; die Schlüssel gelten danach weiter.

Ein Konto hat einen echten Mandanten und einen Testmandanten. Alle Sandbox-Schlüssel eines Kontos arbeiten auf demselben Testmandanten; andere Konten sehen ihn nie.

Welche Umgebung gerade aktiv ist, sagt der Server beim Start (Umgebung: SANDBOX bzw. LIVE) und das Werkzeug mandant_info. Für die ersten Schritte, für Beispiele und für alles, was man ausprobiert, bevor es in die Buchhaltung soll: Sandbox nehmen.

Installation

git clone https://github.com/epago-GmbH/epago-mcp.git
cd epago-mcp
npm install
npm run build        # erzeugt dist/index.js

Einrichtung

Der Server spricht MCP über stdio und wird vom MCP-Client als Prozess gestartet:

EPAGO_API_KEY=epago_... node /absoluter/pfad/zu/epago-mcp/dist/index.js

Variable	Pflicht	Beschreibung
EPAGO_API_KEY	ja	API-Schlüssel im Format epago_…
EPAGO_API_URL	nein	Basis-URL der epago-Instanz, Standard https://app.epago.de

Die meisten MCP-Clients nehmen eine Konfiguration dieser Form entgegen (Name des Servers, Befehl, Argumente, Umgebungsvariablen):

{
  "mcpServers": {
    "epago": {
      "command": "node",
      "args": ["/absoluter/pfad/zu/epago-mcp/dist/index.js"],
      "env": {
        "EPAGO_API_KEY": "epago_...",
        "EPAGO_API_URL": "https://app.epago.de"
      }
    }
  }
}

Statt der Umgebungsvariablen kann eine .env-Datei im Repository-Root liegen (sie ist per .gitignore ausgeschlossen):

EPAGO_API_KEY=epago_...
EPAGO_API_URL=https://app.epago.de

Beim Start ruft der Server /api/v1/me auf, prüft den Schlüssel und registriert die Schreib-Werkzeuge nur, wenn der Schlüssel den Scope write trägt. Ein Schlüssel ohne write sieht die Schreib-Werkzeuge gar nicht erst. Ein ungültiger Schlüssel beendet den Start mit einer Fehlermeldung.

Werkzeuge

Lesen (Scope read)

Werkzeug	Was es tut
mandant_info	Verbindungstest, Stammdaten des Mandanten, Umgebung (LIVE oder SANDBOX), Scopes des Schlüssels
konten_liste	Kontenplan, optional mit Salden für einen Zeitraum
konto_auszug	Kontenblatt eines Kontos mit laufendem Saldo
buchungen_liste	Buchungen mit allen Zeilen, gefiltert nach Datum und Status
rechnungen_liste	Ein- und Ausgangsrechnungen mit Status und Zahlungsstatus
rechnung_zahlungen	Zahlungen eines Belegs mit Betrag, Datum, Buchung und Zahlungsart
kunden_liste	Kunden mit Kundennummer, Anschrift, USt-IdNr. und Zahlungsziel, um Rechnungen zu adressieren
rechnungen_ueberfaellig	Offene Ausgangsrechnungen, standardmäßig nur die überfälligen, mit Tagen überfällig, offenem Betrag und Mahnstufe
bericht_bwa	Betriebswirtschaftliche Auswertung für einen Zeitraum
bericht_ustva	Kennzahlen der Umsatzsteuer-Voranmeldung für einen Zeitraum
salden	Saldenliste aller Konten zu einem Stichtag

Schreiben (Scope write)

Werkzeug	Was es tut
buchung_erstellen	Buchung anlegen, vereinfacht (Betrag, zwei Konten, Steuerschlüssel) oder mit expliziten Zeilen
buchung_stornieren	GoBD-konformer Storno: Gegenbuchung mit Tagesdatum, das Original bleibt stehen
zahlung_erfassen	Zahlung an einem Beleg erfassen; Skonto, Teilzahlung und Forderungsausfall werden abgefragt, nicht geraten
rechnung_erstellen	Ausgangsrechnung anlegen, als Entwurf oder (nur auf ausdrückliche Aufforderung) gebucht; meldet ein Scheitern der Buchung getrennt vom angelegten Entwurf; mit demselben idempotenzSchluessel sicher wiederholbar
beleg_hochladen	Beleg als Base64 hochladen (PDF, Bilder, Tabellen, max. 10 MB)

Die Beschreibungen der Werkzeuge sind bewusst ausführlich: sie sind die Schnittstelle zum Sprachmodell und erklären dort, was GoBD-fest ist, was eine Rückfrage an den Nutzer braucht (Zahlungsart bei offenem Rest, Begründung bei Forderungsausfall) und was nicht geht.

Was man wissen muss

• Gebucht ist gebucht. Eine Buchung mit status: "posted" ist sofort unveränderbar (GoBD). Korrektur nur per buchung_stornieren. Löschen gibt es nicht, auch nicht über die API.
• Festgeschriebene Perioden weisen jede Buchung mit 409 period_closed ab.
• Offener Rest bei einer Zahlung ist eine Entscheidung des Nutzers: Teilzahlung, Skonto oder Forderungsausfall. Ohne zahlungsart antwortet die API mit 400 und liefert Restbetrag, Vorschlag und Optionen mit. § 17 UStG kennt keine Bagatellgrenze.
• Vereinfachte Buchung: buchung_erstellen mit betrag, bruttoKonto, sachKonto und optional steuerschluessel (1 steuerfrei, 2 USt 7 %, 3 USt 19 %, 8 VSt 7 %, 9 VSt 19 %). Den Buchungssatz samt Steuerzeile rechnet der Server mit dem Kontenrahmen des Mandanten (SKR03 oder SKR04); Automatikkonten erkennt er selbst. Die Soll-/Haben-Seite leitet er bei den Schlüsseln 2, 3, 8 und 9 aus dem Steuerfall ab; bei Schlüssel 1 und bei einer Buchung ohne Schlüssel (reine Umbuchung) ist seite (S oder H, bezogen auf das Bruttokonto) Pflicht, weil sie sich dort nicht ableiten lässt. Wer die Zeilen selbst vorgeben will, nutzt lines[]. In beiden Fällen prüft der Server Soll gleich Haben und Steuerkonsistenz.
• Rate-Limit: 60 Aufrufe je Minute und Schlüssel. Bei 429 kurz warten.

Sicherheit

• Der API-Schlüssel kommt ausschließlich aus der Umgebung (EPAGO_API_KEY oder .env). Er wird nur als Authorization: Bearer an die konfigurierte EPAGO_API_URL gesendet und taucht in keiner Ausgabe, keinem Log und keiner Fehlermeldung auf.
• Der Server hält keinen Zustand und speichert nichts auf der Festplatte.
• Schreibende Werkzeuge existieren nur mit write-Scope. Für reine Auswertungen einen Schlüssel ohne write anlegen.
• EPAGO_API_URL nur auf epago selbst setzen. Wer die URL auf einen fremden Host zeigt, schickt seinen Schlüssel dorthin.
• Alle Buchungen über die API laufen in epago durch dieselbe Prüfschicht wie die Oberfläche (Soll gleich Haben, Steuerkonsistenz, Periodensperre, Mandantentrennung). Es gibt keinen zweiten, laxeren Pfad.

Sicherheitslücken bitte nicht als öffentliches Issue melden, sondern an [email protected].

Grenzen

• rechnung_erstellen ist mit demselben Idempotenzschlüssel sicher wiederholbar (ab 0.5.0). Jeder Aufruf sendet den Header Idempotency-Key: den Wert aus idempotenzSchluessel oder, ohne Angabe, eine neue UUID, die in der Antwort und in jeder Fehlermeldung steht. Nach einem Timeout denselben Aufruf mit demselben Schlüssel wiederholen: es entsteht keine zweite Rechnung und keine zweite Buchung (wiederholung: true). Eine Wiederholung bucht auch einen Entwurf nicht nachträglich. Derselbe Schlüssel mit anderem Inhalt wird mit 409 abgewiesen. Kennt der Server den Schlüssel noch nicht und wurde keiner vorgegeben, legt das Werkzeug die Rechnung ohne ihn an und sagt das in der Antwort; dann gilt die alte Regel: nach einem Timeout zuerst mit rechnungen_liste prüfen.
• Die Rechnung wird nur auf ausdrückliche Aufforderung gebucht. Scheitert die Buchung, bleibt der Entwurf stehen; die Antwort nennt den Grund.
• Nicht enthalten: Mahnungen, Versand per E-Mail, PDF-Abruf, Angebote, Gutschriften und das Anlegen von Kunden.

Entwicklung

npm run dev      # startet src/index.ts direkt mit tsx
npm run build    # TypeScript nach dist/

Dieses Repository ist ein Spiegel des Pakets packages/epago-mcp aus dem epago-Monorepo. Issues und Pull Requests sind willkommen; Änderungen werden ins Monorepo übernommen und von dort wieder hierher gespiegelt.

Lizenz

MIT, siehe LICENSE. epago selbst ist ein kommerzieller Dienst der epago GmbH; dieses Repository enthält nur den MCP-Client.