kontist-mcp

Un cliente OAuth2 y una capa GraphQL tipada sobre la banca empresarial de Kontist, expuestos a través del Model Context Protocol para que los saldos, las transacciones y las reservas fiscales puedan leerse y anotarse desde un cliente de herramientas en lugar de desde la aplicación web.

Por qué existe

Kontist es una cuenta empresarial alemana dirigida a autónomos, y mantiene dos cosas que la mayoría de los bancos no exponen de forma útil: subcuentas automáticas de reserva para el IVA y el impuesto sobre la renta, y un campo de anotación por transacción utilizado para la contabilidad. Ambas importan a la hora de hacer la declaración de la renta y ambas resultan tediosas de manejar a mano.

La parte interesante es la cadena de autenticación más que las consultas. Kontist protege su token de actualización de larga duración tras un consentimiento interactivo y una confirmación push MFA en el teléfono, por lo que el token debe capturarse una vez a través de un servidor de devolución local y luego tratarse como la única credencial que merece la pena conservar. Todo lo demás es intercambio de tokens, almacenamiento en caché y gestión de caducidad.

Related MCP server: FinTS-Finanzen

Herramientas

Cada entrada de herramienta se valida con un esquema zod antes de que se envíe una consulta, por lo que un rango de fechas mal formado falla localmente en lugar de como un error de GraphQL.

Cómo funciona

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

La autenticación es OAuth2 con un consentimiento interactivo de una sola vez que genera un token de actualización de larga duración. Solo ese token de actualización va en .env. Los tokens de acceso se obtienen bajo demanda, se almacenan en caché en .tokens-cache.json y se renuevan cuando caducan, por lo que el flujo interactivo se ejecuta exactamente una vez.

Ejecútalo

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

Luego regístralo con tu cliente MCP, apuntando a dist/index.js. El tutorial completo, incluido el registro de la aplicación de desarrollador de Kontist, está en SETUP.md.

Pila tecnológica

Node 18+, TypeScript, @modelcontextprotocol/sdk, graphql-request, el SDK oficial de kontist para el flujo OAuth, zod para la validación de las entradas de las herramientas. Sin ORM y sin framework.

El paso de consentimiento de una sola vez requiere que la aplicación móvil de Kontist esté instalada y con sesión iniciada, porque el token de actualización solo se emite después de que se confirme un push MFA en el teléfono.

Limitaciones

• Principalmente de lectura por diseño. La única escritura es el campo de anotación. Las transferencias no se exponen deliberadamente, aunque la API las soporta y el alcance transfers existe, porque un agente que pueda mover dinero es una mala idea.

• Aún no probado con una cuenta real. El flujo OAuth2, el cliente GraphQL y las siete herramientas están escritos y pasan la verificación de tipos, pero la cuenta en sí se abre una vez que se aprueba el registro de la actividad empresarial. Espera que la primera ejecución real revele deriva de esquema en los campos de transacción.

• Sin suite de pruebas. Dos scripts de humo, test:auth y test:balance, y nada más.

• Cuenta única. Sin soporte para múltiples cuentas, sin paginación más allá de lo que Kontist devuelve por defecto.

Licencia

Apache 2.0. Consulta LICENSE y NOTICE.