kontist-mcp

Клиент OAuth2 и типизированный слой GraphQL поверх Kontist бизнес-банкинга, предоставляемые через Model Context Protocol, чтобы балансы, транзакции и налоговые резервы можно было читать и аннотировать из клиента инструментов, а не из веб-приложения.

Зачем это нужно

Kontist — это немецкий бизнес-счёт, ориентированный на фрилансеров, и в нём есть две вещи, которые большинство банков не предоставляют в удобном виде: автоматические субрасчёта резерва по НДС и подоходному налогу, а также поле аннотации для каждой транзакции, используемое для бухгалтерского учёта. Обе важны при подаче налоговой декларации, и с обеими утомительно работать вручную.

Интересная часть — это цепочка аутентификации, а не запросы. Kontist выдаёт долгоживущий refresh-токен только после интерактивного согласия и подтверждения push-уведомления MFA на телефоне, поэтому токен нужно один раз получить через локальный callback-сервер, а затем рассматривать как единственные учётные данные, которые стоит сохранять. Всё после этого — обмен токенами, кэширование и обработка истечения срока действия.

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 с однократным интерактивным согласием, которое выдаёт долгоживущий refresh-токен. Только этот refresh-токен сохраняется в .env. Access-токены запрашиваются по требованию, кэшируются в .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, официальный SDK kontist для OAuth-процедуры, zod для проверки входных данных инструментов. Никаких ORM и фреймворков.

Для однократного согласия необходимо, чтобы мобильное приложение Kontist было установлено и в него был выполнен вход, потому что refresh-токен выдаётся только после подтверждения push-уведомления MFA на телефоне.

Ограничения

• В основном чтение по замыслу. Единственная операция записи — поле аннотации. Переводы намеренно не предоставляются, даже несмотря на то, что API их поддерживает и существует область transfers, потому что агент, способный перемещать деньги, — плохая идея.

• Пока не проверено на реальном счёте. Поток OAuth2, GraphQL-клиент и все семь инструментов написаны и проходят проверку типов, но сам счёт откроется, как только регистрация предприятия будет завершена. Ожидайте, что первый реальный запуск выявит расхождения схемы в полях транзакций.

• Нет набора тестов. Два smoke-скрипта, test:auth и test:balance, и больше ничего.

• Один счёт. Нет поддержки нескольких счетов, нет пагинации, кроме той, что Kontist возвращает по умолчанию.

Лицензия

Apache 2.0. См. LICENSE и NOTICE.