Skip to main content
Glama
Sign In
deenesjakoruzh
kontist-mcp

kontist-mcp

by Fabi-SPL
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

kontist-mcp

An OAuth2 client and a typed GraphQL layer over Kontist business banking, exposed over the Model Context Protocol so balances, transactions and tax reserves can be read and annotated from a tool client instead of the web app.

Why it exists

Kontist is a German business account aimed at freelancers, and it keeps two things most banks do not expose usefully: automatic VAT and income-tax reserve sub-accounts, and a per-transaction annotation field used for bookkeeping. Both matter at Steuererklärung time and both are tedious to work with by hand.

The interesting part is the auth chain rather than the queries. Kontist gates its long-lived refresh token behind an interactive consent plus an MFA push confirmed on the phone, so the token has to be captured once through a local callback server and then treated as the only credential worth persisting. Everything after that is token exchange, caching and expiry handling.

Related MCP server: FinTS-Finanzen

Tools

Tool

Does

kontist_whoami

Account identity and IBAN, the auth smoke test

kontist_get_balance

Current balance

kontist_list_transactions

Recent transactions, filtered by date, amount or category

kontist_get_transaction

One transaction in full

kontist_get_tax_reserves

VAT and income-tax reserve sub-account balances

kontist_annotate_transaction

Write the bookkeeping note back onto a transaction

kontist_summarize

Inflows, outflows, top counterparties and category totals over a range

Every tool input is validated with a zod schema before a query goes out, so a malformed date range fails locally rather than as a GraphQL error.

How it works

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

Auth is OAuth2 with a one-time interactive consent that yields a long-lived refresh token. Only that refresh token goes in .env. Access tokens are fetched on demand, cached in .tokens-cache.json and refreshed when they expire, so the interactive flow runs exactly once.

Run it

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

Then register it with your MCP client, pointing at dist/index.js. Full walkthrough including the Kontist developer-app registration is in SETUP.md.

Stack

Node 18+, TypeScript, @modelcontextprotocol/sdk, graphql-request, the official kontist SDK for the OAuth dance, zod for tool input validation. No ORM and no framework.

The one-time consent step needs the Kontist mobile app installed and logged in, because the refresh token is only issued after an MFA push is confirmed on the phone.

Limitations

  • Read-mostly by design. The only write is the annotation field. Transfers are deliberately not exposed, even though the API supports them and the transfers scope exists, because an agent that can move money is a bad idea.

  • Not yet exercised against a live account. The OAuth2 flow, the GraphQL client and all seven tools are written and typecheck, but the account itself opens once the Gewerbeanmeldung clears. Expect the first real run to turn up schema drift in the transaction fields.

  • No test suite. Two smoke scripts, test:auth and test:balance, and nothing else.

  • Single account. No multi-account handling, no pagination beyond what Kontist returns by default.

License

Apache 2.0. See LICENSE and NOTICE.

Available Tools

7 tools
kontist_annotate_transactionA

Add a note/annotation to a transaction. Useful for tagging Stripe payouts with the originating customer or invoice.

Inputs: id (required), note (required).

kontist_get_balanceA

Return the current Kontist business account balance, IBAN, and available balance (in EUR).

Inputs: no named parameters.

kontist_get_tax_reservesA

Get current balances of the Kontist VAT and income tax reserve sub-accounts. Returns null fields if not enabled or if Kleinunternehmer (no VAT).

Inputs: no named parameters.

kontist_get_transactionA

Fetch a single Kontist transaction by its ID.

Inputs: id (required).

kontist_list_transactionsB

List recent Kontist transactions with optional filters. Default returns last 50. Amounts are in EUR (positive = inflow, negative = outflow).

Inputs: to, from, limit, cursor, +2 more.

kontist_summarizeA

High-level financial summary for a date range: inflows, outflows, net, top counterparties, category breakdown. Default = last 30 days.

Inputs: to, from.

kontist_whoamiA

Verify Kontist auth is working and return basic identity. Run this first to confirm credentials before any other call.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct concern: identity, balance, transaction listing, single transaction lookup, tax reserves, annotation, and summary. Even the two balance tools are clearly separated by account type, and list/get transaction follow a standard collection/detail split.

    Naming Consistency4/5

    All tools share the kontist_ prefix and use snake_case, with a consistent verb_noun structure for most tools (get_balance, list_transactions, get_transaction, get_tax_reserves, annotate_transaction, summarize). The only outlier is kontist_whoami, which uses a command-style name rather than a verb_noun pattern.

    Tool Count5/5

    Seven tools is an appropriate size for a banking/finance-focused MCP server. Each tool provides a meaningful capability without redundancy or padding, and the count is neither too thin nor overwhelming.

    Completeness5/5

    The toolset covers the core Kontist workflow: auth verification, balance, transaction browsing and detail lookup, tax reserve visibility, annotation, and period summaries. There are no obvious dead ends for the stated scope of reading and annotating account data.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • banktivity-mcp

      mhriemers
      A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for accessing and managing Banktivity personal finance data, enabling account, transaction, and budget operations through natural language.
      3
      MIT

    • FinTS-Finanzen

      NG-Bullseye
      A
      license
      Not graded
      quality
      C
      maintenance
      Read-only MCP server for FinTS/HBCI banking; enables account information retrieval such as balances and transactions via PIN-TAN.
      1
      MIT

    • bank.mcp

      owieschon
      A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that turns bank transactions into a financial digest including cash-flow forecast, spending breakdown, fee detection, and receipt reconciliation, exposing deterministic engines as JSON-RPC tools.
      Apache 2.0

    • pocketledger

      ektamishra4321
      F
      license
      Not graded
      quality
      D
      maintenance
      MCP server for personal finance management. Enables natural language expense logging, budgeting, recurring charge detection, and statement import with deterministic local calculations.
      -