kontist-mcp

Kontistの法人銀行業務に対するOAuth2クライアントおよび型付きGraphQLレイヤーであり、Model Context Protocolを通じて公開されている。これにより、残高・取引・税引当金をウェブアプリではなくツールクライアントから読み取り、注釈を付けることができる。

存在理由

Kontistはフリーランサー向けのドイツの法人銀行口座であり、ほとんどの銀行が有用な形で公開していない2つのものを保持している。自動付加価値税（VAT）および所得税の引当金サブアカウントと、簿記に使用される取引ごとの注釈フィールドである。どちらも確定申告の時期に重要であり、手作業で処理するには退屈である。

興味深いのはクエリではなく認証チェーンである。Kontistは長期有効なリフレッシュトークンを、対話型の同意と電話でのMFAプッシュ確認の背後に置いている。そのため、トークンはローカルのコールバックサーバーを通じて一度だけ取得し、その後は永続化する価値のある唯一の資格情報として扱う必要がある。それ以降は、トークン交換、キャッシュ、有効期限処理のみである。

Related MCP server: FinTS-Finanzen

ツール

すべてのツール入力は、クエリが送信される前に zod スキーマで検証されるため、不正な日付範囲はGraphQLエラーではなくローカルで失敗する。

仕組み

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

認証はOAuth2で、一度だけの対話型同意により長期有効なリフレッシュトークンが発行される。.env に入るのはそのリフレッシュトークンだけである。アクセストークンはオンデマンドで取得され、.tokens-cache.json にキャッシュされ、有効期限が切れると更新されるため、対話型フローは正確に一度だけ実行される。

実行方法

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

次に、dist/index.js を指定してMCPクライアントに登録する。Kontist開発者アプリの登録を含む完全な手順は SETUP.md にある。

技術スタック

Node 18+、TypeScript、@modelcontextprotocol/sdk、graphql-request、OAuthのやり取りのための公式 kontist SDK、ツール入力検証のための zod。ORMもフレームワークもない。

一度だけの同意ステップでは、Kontistモバイルアプリがインストールされログインしている必要がある。リフレッシュトークンは、電話でのMFAプッシュ確認後にのみ発行されるためである。

制限事項

• 設計上、読み取りが中心。 唯一の書き込みは注釈フィールドのみ。APIが送金をサポートし、transfers スコープが存在するにもかかわらず、送金は意図的に公開していない。資金を動かせるエージェントは悪い考えだからだ。

• 実アカウントでの検証はまだ。 OAuth2フロー、GraphQLクライアント、7つのツールはすべて作成済みで型チェックも通っているが、アカウント自体はGewerbeanmeldungの完了後に開設される。最初の実実行では、取引フィールドにスキーマのズレが見つかるだろう。

• テストスイートなし。 test:auth と test:balance の2つのスモークスクリプトのみ。

• 単一アカウント。 マルチアカウント処理はなく、Kontistがデフォルトで返す以上のページネーションもない。

ライセンス

Apache 2.0。LICENSE と NOTICE を参照。