Version 0.4.0 · MIT

MCP-Server für epago

epago-mcp verbindet KI-Assistenten, die das Model Context Protocol sprechen (etwa Claude, Codex und andere MCP-fähige Werkzeuge), mit deiner Buchhaltung: Kontenplan, Buchungen, Rechnungen, Kunden, Zahlungen, Belege, BWA und Umsatzsteuer-Voranmeldung.

Der Server läuft lokal als Prozess (stdio) und ist ein reiner Client derPublic API v1. Er hat keinen Zugriff auf eine Datenbank, speichert keine Zugangsdaten und hat keine Lösch-Werkzeuge. Jeder Schreibzugriff läuft in epago durch dieselbe Prüfschicht wie die Oberfläche: Soll gleich Haben, Steuerkonsistenz, Periodensperre, Mandantentrennung.

Quelltext auf GitHub API-Referenz API-Schlüssel anlegen

Voraussetzungen

Ein epago-Account unter app.epago.de.
Node.js 20 oder neuer.
Ein API-Schlüssel aus epago, angelegt unter Mein Konto → API-Schlüssel(Anleitung). Der Klartext-Schlüssel wird nur einmal angezeigt.

Scope `read`

Der Server registriert nur die Lese-Werkzeuge. Für reine Auswertungen genügt das.

Scope `write`

Zusätzlich die Schreib-Werkzeuge. Beim Start fragt der Server/api/v1/me ab; ein Schlüssel ohnewrite sieht die Schreib-Werkzeuge gar nicht erst.

Zum Ausprobieren: ein Sandbox-Schlüssel

Jedes epago-Konto hat neben der echten Buchhaltung einen Testmandanten mit Beispieldaten. Ein Schlüssel mit dem Präfix epago_test_erreicht ausschließlich diesen Testmandanten und nie die echte Buchhaltung: die Trennung hängt am Schlüssel selbst, nicht an einer Einstellung im Client.

Aus dem Testmandanten geht nichts nach außen: keine E-Mail, keine ELSTER-Übermittlung, keine Bankverbindung, keine Zahlung.
Eine Testbuchung ist trotzdem eine richtige Buchung, mit denselben GoBD-Regeln. Wer neu anfangen will, setzt den Testmandanten zurück; die Schlüssel gelten danach weiter.
Welche Umgebung aktiv ist, meldet der Server beim Start (Umgebung: SANDBOX bzw. LIVE) und das Werkzeug mandant_info.

Mehr zur Sandbox auf der Entwicklerseite.

Installation und Einrichtung

1. Bauen

Das Paket ist nicht auf npm veröffentlicht. Der Server wird aus dem Quelltext gebaut und mit Node.js gestartet.

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

2. Im MCP-Client eintragen

Der Client startet den Server als Prozess. Die meisten MCP-Clients nehmen eine Konfiguration dieser Form entgegen (Name des Servers, Befehl, Argumente, Umgebungsvariablen); wo genau sie liegt, steht in der Dokumentation deines Clients.

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

Zum Prüfen direkt auf der Kommandozeile:

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

Variable	Pflicht	Bedeutung
`EPAGO_API_KEY`	ja	API-Schlüssel im Format epago_… (Sandbox: epago_test_…)
`EPAGO_API_URL`	nein	Basis-URL der epago-Instanz, Standard https://app.epago.de. Nur https://, http:// ausschließlich auf localhost.

Statt der Umgebungsvariablen kann eine .env-Datei im Wurzelverzeichnis des Repositorys liegen. Ein ungültiger Schlüssel beendet den Start mit einer Fehlermeldung.

Werkzeuge

16 Werkzeuge in Version 0.4.0: 11 zum Lesen,5 zum Schreiben. Die Beschreibungen, die das Sprachmodell sieht, sind ausführlicher; sie erklären dort, was GoBD-fest ist und was eine Rückfrage an dich braucht.

Lesenread

Werkzeug	Was es tut
`mandant_info`	Verbindungstest, Stammdaten des Mandanten, Umgebung (LIVE oder SANDBOX) und Scopes des Schlüssels.
`konten_liste`	Kontenplan, optional mit Salden für einen Zeitraum.
`konto_auszug`	Kontenblatt eines Kontos mit laufendem Saldo.
`salden`	Saldenliste aller Konten zu einem Stichtag.
`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.

Schreibenwrite

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.
`beleg_hochladen`	Beleg als Base64 hochladen (PDF, Bilder, Tabellen).

Was man wissen muss

Gebucht ist gebucht. Eine gebuchte Buchung 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.
Ein offener Rest bei einer Zahlung ist deine Entscheidung: Teilzahlung, Skonto oder Forderungsausfall. Ohne Angabe antwortet die API mit Restbetrag, Vorschlag und Optionen.
rechnung_erstellen hat keinen Idempotenzschlüssel. Nach einem Timeout nicht blind wiederholen, sondern zuerst mit rechnungen_liste prüfen, ob die Rechnung schon existiert. Gebucht wird nur auf ausdrückliche Aufforderung; scheitert die Buchung, bleibt der Entwurf stehen und die Antwort nennt den Grund.
Belege: die API nimmt bis 10 MB an, die Plattform begrenzt eine Anfrage aber schon bei 4,5 MB. Als Base64 passt eine Datei bis rund 3 MB durch.
Rate-Limit: 60 Anfragen je Minute und Live-Schlüssel, 30 je Sandbox-Schlüssel. Bei 429 nennt der Server die Wartezeit aus Retry-After.
Nicht enthalten: Mahnungen, Versand per E-Mail, PDF-Abruf, Angebote, Gutschriften, das Anlegen von Kunden und jedes Löschen.

Sicherheit

Schlüssel

Kommt ausschließlich aus der Umgebung und geht nur alsAuthorization: Bearer an die konfigurierte API-URL. Er steht in keiner Ausgabe, keinem Log und keiner Fehlermeldung und lässt sich in epago jederzeit widerrufen.

Nur HTTPS

EPAGO_API_URL muss mithttps:// beginnen, sonst startet der Server nicht. http:// ist nur auf localhost erlaubt. Die URL nur auf epago selbst setzen: wer sie auf einen fremden Host zeigt, schickt seinen Schlüssel dorthin.

Zeit- und Größengrenze

Jeder Aufruf endet nach 60 Sekunden, und eine Antwort über 16 MB wird abgebrochen, statt den Speicher zu füllen.

Kein Zustand

Der Server speichert nichts auf der Festplatte. Schreib-Werkzeuge existieren nur mitwrite-Scope.

Sicherheitslücken bitte nicht als öffentliches Issue melden, sondern anservice@epago.de.

Quelltext und Lizenz

Das Repository auf GitHub ist ein Spiegel des Pakets aus dem epago-Monorepo, LizenzMIT. Issues und Pull Requests sind willkommen. epago selbst ist ein kommerzieller Dienst der epago GmbH; das Repository enthält nur den MCP-Client.

github.com/epago-GmbH/epago-mcp Zur API-Referenz