kontist-mcp

Kontist 비즈니스 뱅킹을 위한 OAuth2 클라이언트이자 타입이 지정된 GraphQL 계층으로, Model Context Protocol을 통해 노출되어 잔액, 거래 내역, 세금 준비금을 웹 앱 대신 도구 클라이언트에서 읽고 주석을 달 수 있습니다.

존재 이유

Kontist는 프리랜서를 대상으로 하는 독일 비즈니스 계정으로, 대부분의 은행이 유용하게 노출하지 않는 두 가지를 제공합니다. 자동 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 클라이언트 및 일곱 가지 도구는 모두 작성되었고 타입 검사를 통과했지만, 계정 자체는 사업자 등록이 통과된 후에 개설됩니다. 첫 실제 실행에서 거래 필드에 스키마 드리프트가 나타날 것으로 예상하세요.

• 테스트 스위트 없음. test:auth 및 test:balance라는 두 개의 스모크 스크립트뿐입니다.

• 단일 계정. 다중 계정 처리가 없고, Kontist가 기본으로 반환하는 것 이상의 페이징도 없습니다.

라이선스

Apache 2.0. LICENSE 및 NOTICE를 참조하세요.