kontist-mcp

一个 OAuth2 客户端和基于 Kontist 企业银行业务的带类型 GraphQL 层， 通过 Model Context Protocol 暴露，使余额、交易和税务储备可以从工具客户端读取和标注，而无需使用 Web 应用。

为什么存在

Kontist 是一个面向自由职业者的德国企业账户，它保留了两项大多数银行不会以有用方式提供的功能：自动增值税和所得税储备子账户，以及用于记账的每笔交易备注字段。这两项在报税时都很重要，而且手动处理起来都很繁琐。

有趣的部分是认证链而不是查询本身。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

然后用你的 MCP 客户端注册它，指向 dist/index.js。包含 Kontist 开发者应用注册的完整指南见 SETUP.md。

技术栈

Node 18+、TypeScript、@modelcontextprotocol/sdk、graphql-request、用于 OAuth 流程的官方 kontist SDK，以及用于工具输入验证的 zod。没有使用 ORM 和框架。

一次性同意步骤需要安装并登录 Kontist 移动应用，因为刷新令牌只有在手机确认 MFA 推送后才会签发。

限制

• 设计上以读取为主。 唯一的写入是备注字段。转账被有意不暴露，尽管 API 支持转账且存在 transfers 权限范围，因为一个能够移动资金的代理是个坏主意。

• 尚未在真实账户上验证。 OAuth2 流程、GraphQL 客户端和全部七个工具都已编写并通过类型检查，但账户本身要等到工商登记通过后才会开通。预计首次真实运行会发现交易字段中的 schema 漂移。

• 没有测试套件。 只有两个冒烟脚本：test:auth 和 test:balance，没有其他内容。

• 单一账户。 不支持多账户处理，除 Kontist 默认返回的内容外没有分页。

许可证

Apache 2.0。参见 LICENSE 和 NOTICE。