kontist-mcp

Ein OAuth2-Client und eine typisierte GraphQL-Schicht über das Geschäftskonto von Kontist, bereitgestellt über das Model Context Protocol, sodass Kontostände, Transaktionen und Steuerrücklagen von einem Tool-Client statt aus der Web-App gelesen und annotiert werden können.

Warum es das gibt

Kontist ist ein deutsches Geschäftskonto für Freiberufler und bietet zwei Dinge, die die meisten Banken nicht sinnvoll zur Verfügung stellen: automatische Unterkonten für Umsatzsteuer- und Einkommensteuerrücklagen sowie ein Annotationsfeld pro Transaktion für die Buchhaltung. Beides ist zur Steuererklärung wichtig und beides ist mühsam von Hand zu bearbeiten.

Der interessante Teil ist die Authentifizierungskette und nicht die Abfragen. Kontist sichert sein langlebiges Refresh-Token durch eine interaktive Zustimmung plus einen auf dem Telefon bestätigten MFA-Push ab. Das Token muss daher einmal über einen lokalen Callback-Server erfasst und anschließend als einzige zu speichernde Anmeldedaten behandelt werden. Alles danach ist Token-Austausch, Caching und Ablaufverwaltung.

Related MCP server: FinTS-Finanzen

Tools

Jede Tool-Eingabe wird vor dem Absenden einer Abfrage mit einem zod-Schema validiert, sodass ein fehlerhafter Datumsbereich lokal und nicht als GraphQL-Fehler abgelehnt wird.

So funktioniert es

tool client
  |  MCP over stdio
kontist-mcp (Node + TypeScript)
  |  GraphQL over fetch, OAuth2 bearer, token refreshed and cached
api.kontist.com/api/graphql

Die Authentifizierung erfolgt über OAuth2 mit einer einmaligen interaktiven Zustimmung, die ein langlebiges Refresh-Token erzeugt. Nur dieses Refresh-Token kommt in .env. Access-Tokens werden bei Bedarf abgerufen, in .tokens-cache.json zwischengespeichert und bei Ablauf erneuert, sodass der interaktive Ablauf genau einmal durchläuft.

Ausführen

npm install
cp .env.example .env        # client id, client secret
npm run setup               # one-time OAuth consent, writes the refresh token
npm run test:auth           # confirms the token works
npm run build

Registrieren Sie es dann bei Ihrem MCP-Client und verweisen Sie auf dist/index.js. Eine vollständige Anleitung einschließlich der Registrierung der Kontist-Entwickler-App finden Sie in SETUP.md.

Stack

Node 18+, TypeScript, @modelcontextprotocol/sdk, graphql-request, das offizielle kontist-SDK für den OAuth-Ablauf, zod für die Validierung von Tool-Eingaben. Kein ORM und kein Framework.

Für den einmaligen Zustimmungsschritt muss die Kontist-Mobile-App installiert und angemeldet sein, da das Refresh-Token erst nach Bestätigung eines MFA-Pushs auf dem Telefon ausgegeben wird.

Einschränkungen

• Hauptsächlich lesend ausgelegt. Der einzige Schreibvorgang ist das Annotationsfeld. Überweisungen sind bewusst nicht freigeschaltet, obwohl die API sie unterstützt und der Scope transfers existiert, denn ein Agent, der Geld bewegen kann, ist keine gute Idee.

• Noch nicht mit einem Live-Konto getestet. Der OAuth2-Ablauf, der GraphQL-Client und alle sieben Tools sind geschrieben und typgeprüft, aber das Konto selbst wird erst eröffnet, sobald die Gewerbeanmeldung durch ist. Erwarten Sie beim ersten echten Lauf Schema-Abweichungen bei den Transaktionsfeldern.

• Keine Testsuite. Zwei Smoke-Skripte, test:auth und test:balance, und sonst nichts.

• Einzelnes Konto. Keine Multi-Konto-Verwaltung, keine Paginierung über das hinaus, was Kontist standardmäßig zurückgibt.

Lizenz

Apache 2.0. Siehe LICENSE und NOTICE.