YNAB MCP Starter

Repositorio de inicio de TypeScript estilo producción para un servidor MCP de YNAB de solo lectura.

Este starter es intencionalmente pequeño y explícito:

• Node.js 18+

• TypeScript con configuraciones de compilador estrictas

• Entradas y salidas de herramientas validadas con Zod

• Cliente de API de YNAB de solo lectura con reintentos y manejo de tiempos de espera

• Pruebas unitarias con respuestas de YNAB simuladas

• Marcadores TODO claros donde se debe conectar el transporte MCP

Qué incluye este repositorio

src/
  clients/   YNAB API client, environment config, and error types
  schemas/   strict Zod schemas for tool contracts
  server/    MCP server composition and transport TODO placeholders
  tools/     read-only business logic for each YNAB capability
  types/     shared API and service types
tests/       unit tests with mocked API responses

Funcionalidades de solo lectura implementadas:

• listar presupuestos

• listar cuentas

• listar categorías

• listar transacciones recientes

• buscar transacciones sin categorizar

• gasto mensual por categoría

El acceso de escritura no está implementado intencionalmente.

Related MCP server: MCP Server Starter

Configuración

1. Instalar dependencias:

npm install

2. Copiar el archivo de entorno de ejemplo:

cp .env.example .env

3. Establecer su token de YNAB en .env:

YNAB_TOKEN=your-token-here

4. Ejecutar el modo de desarrollo local:

npm run dev

Scripts

• npm run build compila TypeScript en dist/

• npm run dev ejecuta el punto de entrada del starter con observación de archivos

• npm run lint ejecuta ESLint

• npm run test ejecuta pruebas unitarias con Vitest

• npm run typecheck ejecuta TypeScript en modo no-emit

Conexión MCP

El repositorio incluye la capa de composición del servidor, pero aún no lo vincula a un transporte específico.

Busque los comentarios TODO en:

• src/server/index.ts

• src/server/registerTools.ts

Ahí es donde debería:

1. Instanciar el servidor MCP

2. Registrar definiciones de herramientas y esquemas

3. Conectar stdio, SSE u otro transporte

4. Agregar registro estructurado y ganchos operativos

Notas de seguridad

• Este starter espera un token de acceso personal YNAB_TOKEN en las variables de entorno.

• Nunca codifique el token en archivos fuente, pruebas, prompts o registros.

• Mantenga el token limitado al uso operativo de solo lectura y rótelo si se expone.

• Evite registrar respuestas sin procesar de la API de YNAB en producción, ya que pueden contener notas de transacciones u otros metadatos financieros confidenciales.

• Este starter solo realiza solicitudes GET a la API de YNAB. No se han implementado endpoints de escritura.

Notas de diseño

• El cliente de YNAB centraliza los reintentos, el manejo de tiempos de espera y la normalización de errores.

• Los módulos de herramientas están aislados de los detalles HTTP y operan sobre una pequeña interfaz de servicio.

• Los esquemas de Zod validan tanto las entradas como las salidas de las herramientas para detectar desviaciones a tiempo.

• Los importes de dinero se exponen tanto en miliunidades de YNAB como en importes decimales fáciles de leer para los humanos.

• El gasto mensual por categoría solo cuenta las salidas para el mes solicitado.

Ejemplos de prompts

• "List my YNAB budgets."

• "Show the accounts in budget budget-id-123."

• "List categories for budget budget-id-123."

• "Show the most recent 20 transactions in budget budget-id-123."

• "Find uncategorized transactions in budget budget-id-123 since 2026-04-01."

• "Summarize monthly spend by category for budget budget-id-123 in 2026-04."

Pruebas

Las pruebas simulan las respuestas de la API de YNAB para que pueda validar el comportamiento sin un token real:

npm run test

Ideas para el fortalecimiento en producción

• Agregar IDs de correlación de solicitudes y registros estructurados

• Agregar métricas sobre reintentos, limitación de tasa y latencia

• Agregar pruebas de integración contra una capa HTTP simulada

• Agregar controles de paginación de resultados si su cliente MCP espera conjuntos de resultados más grandes

• Agregar una integración de gestor de secretos en lugar de archivos .env locales para la implementación