MCP Server for YNAB

Un servidor MCP que conecta asistentes de IA a tu presupuesto de YNAB: solo lectura por defecto, con escrituras opcionales que se registran y son reversibles.

GitHub

Prueba este MCPPatrocinado

Documentación

MCP Server para YNAB

Pregúntale a tu presupuesto. Conecta Claude, Codex, Cursor o cualquier cliente MCP a YNAB y obtén respuestas sobre tu dinero real: cómo va el mes, qué está sobregirado, cuánto cuestan realmente tus suscripciones.

A terminal session asking how the month is going and what subscriptions cost, answered by the server from a sample budget

YNAB_API_KEY=your_token uvx mcp-server-for-ynab smoke

Solo lectura por defecto. Las herramientas de escritura no se registran en absoluto a menos que establezcas YNAB_ALLOW_WRITES=1, por lo que nunca aparecen para el asistente y nada puede cambiar tu presupuesto hasta que tú lo decidas. Cuando las habilitas, cada escritura registra el estado que la precedió y se puede deshacer.

Un servidor MCP que expone la API de YNAB como herramientas y luego añade herramientas enriquecidas que responden preguntas que la API cruda no puede responder en una sola llamada: salud del presupuesto, colas de limpieza, análisis de gastos, cargos recurrentes.

Inicio Rápido

1. Obtén un token de YNAB

Genera un token de acceso personal en app.ynab.com/settings/developer.

También necesitas uv, que proporciona uvx:

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS and Linux
brew install uv                                   # macOS with Homebrew
winget install --id=astral-sh.uv -e               # Windows

Verifica que ambos funcionen. No hay nada que clonar: uvx descarga el paquete y lo ejecuta en un entorno desechable:

YNAB_API_KEY=your_token uvx mcp-server-for-ynab smoke

smoke valida la configuración y el registro de herramientas, y luego sale. Debería imprimir smoke: app created, 44 tools registered.

2. Añádelo a tu cliente

Cliente	Configuración
Claude Code	un comando
Claude Desktop	archivo de configuración
Cursor	enlace de un clic
VS Code (GitHub Copilot)	un comando
Codex CLI	un comando
Gemini CLI	un comando
Windsurf, Zed, otros	configuración stdio genérica
MCP Inspector	depuración

Las dos rutas más comunes:

Claude Code — instala el plugin, que trae su propia configuración de MCP:

/plugin marketplace add hs737/mcp-server-for-ynab
/plugin install mcp-server-for-ynab@mcp-server-for-ynab

O registra el servidor directamente, si prefieres no usar un plugin:

claude mcp add --env YNAB_API_KEY=your_ynab_token --transport stdio --scope user \
  ynab -- uvx mcp-server-for-ynab stdio

Claude Desktop, Cursor, Windsurf y la mayoría de los demás — pega esto en el archivo de configuración MCP del cliente:

{
  "mcpServers": {
    "ynab": {
      "command": "uvx",
      "args": ["mcp-server-for-ynab", "stdio"],
      "env": {
        "YNAB_API_KEY": "your_ynab_token",
        "YNAB_PLAN_ID": "your_plan_id"
      }
    }
  }
}

YNAB_PLAN_ID es opcional pero recomendado: con él configurado, nunca tienes que nombrar un presupuesto en una solicitud. Instrucciones completas por cliente, incluyendo dónde vive cada archivo de configuración y cómo mantener el token fuera de él, están en Configuración del Cliente.

Hosts de escritorio que aceptan paquetes — descarga el archivo .mcpb de la última versión y ábrelo. El host te pide tu token en un formulario y lo almacena en el llavero de tu sistema operativo, por lo que no hay archivo de configuración que editar ni token en texto plano. Una casilla de verificación controla si las escrituras están habilitadas.

Docker

Hay una imagen publicada disponible para linux/amd64 y linux/arm64. El servidor habla MCP a través de stdin y stdout, así que ejecútalo adjunto con -i. No hay puerto que publicar:

docker run -i --rm -e YNAB_API_KEY=your_ynab_token \
  ghcr.io/hs737/mcp-server-for-ynab

O constrúyelo tú mismo desde un clon:

docker build -t mcp-server-for-ynab .
docker run -i --rm -e YNAB_API_KEY=your_ynab_token mcp-server-for-ynab

Si habilitas escrituras, monta un volumen para el historial; de lo contrario, --rm descarta el registro que hace posible una reversión:

docker run -i --rm -e YNAB_API_KEY=your_ynab_token -e YNAB_ALLOW_WRITES=1 \
  -v ynab-mcp-history:/home/app/.mcp-server-for-ynab mcp-server-for-ynab

3. Hazle una pregunta

¿Cuál es mi posición de efectivo en todas las cuentas?

Si eso funciona, estás listo. Si no funciona, consulta Solución de Problemas — la causa habitual es que el cliente no puede encontrar uvx en su PATH.

Qué Puedes Preguntar

Solo lectura, funciona de inmediato:

Pregunta	Herramienta que utiliza
"¿Cómo va el presupuesto de este mes?"	`overview_month_health`
"¿Cuál es mi posición de efectivo en todas las cuentas?"	`overview_cash_position`
"¿Qué transacciones aún necesitan una categoría?"	`triage_uncategorized`
"¿Qué está esperando mi aprobación?"	`triage_unapproved`
"¿Qué categorías están sobregiradas y por cuánto?"	`analysis_overspent_categories`
"¿Qué objetivos no se financiarán este mes?"	`analysis_target_funding_gaps`
"¿Hay transacciones programadas en riesgo?"	`analysis_upcoming_scheduled_risks`
"¿Qué he gastado en este beneficiario durante el último año?"	`bookkeeping_transaction_history`
"¿Qué suscripciones estoy pagando realmente?"	`analysis_recurring_charges`

Con YNAB_ALLOW_WRITES=1:

Categoriza las transacciones sin categorizar de la semana pasada y luego muéstrame lo que cambiaste.

El agente categoriza, y history_list muestra cada escritura con el valor que la precedió. history_revert deshace cualquiera de ellas.

Los agentes funcionan mejor cuando comienzan con overview_available_tools, que devuelve el catálogo actual de herramientas agrupado por familia. Consulta Superficie de Herramientas para el mapa completo.

Flujos de trabajo guiados

Seis indicaciones vienen con el servidor, y la mayoría de los clientes las muestran como comandos de barra: un punto de partida que no requiere leer primero la lista de herramientas: revisión mensual, triaje semanal, categorizar y aprobar, auditoría de suscripciones, posición de efectivo y revisar y deshacer.

Tres recursos (ynab://guide/*) contienen el método YNAB, las reglas de seguridad de escritura y orientación sobre qué herramienta usar. Se obtienen bajo demanda, por lo que no cuestan nada hasta que un cliente los solicite.

Configuración

Variable	Requerida	Descripción
`YNAB_API_KEY`	Sí	Token de acceso personal de YNAB
`YNAB_PLAN_ID`	Recomendada	ID de plan por defecto, haciendo `plan_id` opcional en la mayoría de las herramientas
`YNAB_ALLOW_WRITES`	No	Registra herramientas de escritura. Sin establecer significa solo lectura
`YNAB_HISTORY_PATH`	No	Archivo de historial de escrituras, por defecto `~/.mcp-server-for-ynab/history.jsonl`
`YNAB_RATE_LIMIT_PER_HOUR`	No	Presupuesto de solicitudes del lado del cliente, por defecto `190` de los 200 de YNAB
`YNAB_RATE_WARN_THRESHOLD`	No	Advertir cuando queden esta cantidad de solicitudes, por defecto `50`
`LOG_LEVEL`	No	Verbosidad del registro, por defecto `INFO`

Establece estas en el bloque env de tu cliente MCP. Para desarrollo local, copia .env.example a .env y complétalo.

Límites de tasa

YNAB permite 200 solicitudes por hora por token, y una sola herramienta enriquecida puede consumir varias. El servidor rastrea su propio uso en una hora móvil y se detiene justo por debajo del límite de YNAB, por lo que el límite que alcanzas es local y se informa claramente en lugar de un 429 en medio de un flujo de trabajo. Llama a overview_request_budget para ver lo que queda; no cuesta solicitudes de API.

Familias de Herramientas

45 herramientas de solo lectura, 64 con escrituras habilitadas, más 6 indicaciones guiadas y 3 recursos de referencia.

Familia	Tipo	Propósito
`overview`	enriquecida	Instantáneas de salud del presupuesto y orientación
`triage`	enriquecida	Colas de limpieza de transacciones
`bookkeeping`	enriquecida	Sugerencias de categorización, ayuda con notas, historial
`analysis`	enriquecida	Análisis de gastos, brechas de financiamiento, riesgos programados
`history`	enriquecida	Revisar y revertir escrituras hechas por este servidor
`user`	cruda	Información del usuario de YNAB
`plans`	cruda	Lecturas de plan y configuración
`accounts`	cruda	Lecturas y creación de cuentas
`categories`	cruda	Categorías y grupos de categorías
`months`	cruda	Datos de presupuesto a nivel de mes
`payees`	cruda	Gestión de beneficiarios
`payee_locations`	cruda	Metadatos geográficos de beneficiarios, nicho/baja prioridad
`transactions`	cruda	CRUD de transacciones y disparador de importación
`scheduled_transactions`	cruda	Gestión de transacciones programadas
`money_movements`	cruda	Datos de movimiento de dinero

Herramientas crudas son espejos cercanos de los endpoints de YNAB: úsalas para lecturas exactas y todas las escrituras. Herramientas enriquecidas combinan varias lecturas en una sola respuesta: úsalas para orientación, investigación y análisis. Cada herramienta está etiquetada como read o write, y las herramientas enriquecidas no realizan escrituras ocultas.

Más detalles: Superficie de Herramientas

Herramientas de Escritura

Las herramientas de escritura no se registran a menos que optes por ellas:

YNAB_ALLOW_WRITES=1

Sin esto, el servidor es de solo lectura y las herramientas de escritura están ausentes de tools/list — un agente no puede llamar a lo que no puede ver. Esto es deliberado: el servidor tiene una credencial que puede modificar registros financieros reales, y rechazar una llamada en el momento de la ejecución aún anunciaría la capacidad.

Cada escritura se registra y la mayoría se puede deshacer

Cuando las escrituras están habilitadas, cada una registra el estado que existía antes de ella. YNAB no tiene un endpoint de historial, por lo que esta es la única forma de recuperar un valor sobrescrito.

Herramienta	Propósito
`history_list`	Escrituras recientes, más nuevas primero, cada una marcada como reversible o no
`history_show`	Una entrada completa, incluido el estado anterior
`history_revert`	Deshacer una escritura
`history_revert_to`	Revertir el plan a su estado en una entrada elegida

history_revert_to deshace todo después de la entrada que nombres, de la más nueva a la más antigua, porque las ediciones superpuestas en el mismo registro solo se componen correctamente en orden inverso. La reversión en sí misma se registra, por lo que una reversión se puede revertir.

Lo que no se puede deshacer. YNAB no tiene una ruta de eliminación para cuentas, categorías, grupos de categorías o beneficiarios, por lo que crear uno es permanente. Esas operaciones se registran como no reversibles con el motivo, y una reversión las informa bajo blocked en lugar de omitirlas silenciosamente: una reversión incompleta que afirma éxito es peor que una que te dice lo que dejó atrás. Una transacción recreada también obtiene una nueva identificación y pierde cualquier vínculo de importación bancaria.

Las escrituras se verifican, no se asumen

Las herramientas que cambian un valor lo releen después y reportan un bloque verification. Una respuesta 200 no es prueba: YNAB acepta budgeted en la ruta de actualización de categoría, devuelve 200 y lo ignora. La verificación es lo que detecta eso.

Convención de Montos

Todos los montos monetarios de YNAB están en milliunits: 1000 = $1.00.

Las herramientas crudas aceptan y devuelven milliunits para campos de monto canónicos.
Las herramientas enriquecidas pueden incluir ayudas de visualización junto con valores canónicos.

Tus Datos

Este servidor almacena exactamente una cosa en tu máquina: un registro de las escrituras que hizo, utilizado por history_revert. No se envía nada a ningún lugar excepto api.ynab.com, y no hay telemetría.

uvx mcp-server-for-ynab history --show          # where it is, how much is there
uvx mcp-server-for-ynab history --export out.json
uvx mcp-server-for-ynab history --delete        # also removes the ability to revert

Estos no necesitan credenciales ni agente: recuperar tus datos, o eliminarlos, no debería requerir ejecutar un LLM.

Para Colaboradores

Este repositorio está estructurado para que un colaborador o agente de IA pueda responder tres preguntas rápidamente: dónde vive el servidor MCP, dónde viven los envoltorios y modelos de la API de YNAB, y dónde agregar nuevas herramientas, pruebas y documentación.

flowchart LR
    A["MCP Client"] --> B["FastMCP Server"]
    B --> C["Tool Handlers"]
    C --> D["ynab_client"]
    D --> E["http_client (httpx)"]
    E --> F["YNAB API"]
    C --> G["enriched/"]
    G --> D

El código se centra en un pequeño conjunto de capas:

src/mcp_server_for_ynab/server/: aplicación FastMCP, metadatos de herramientas, registro de herramientas, límite de errores
src/mcp_server_for_ynab/ynab_client/: un módulo envoltorio asíncrono por familia de recursos de YNAB
src/mcp_server_for_ynab/http_client/: envoltorio httpx saliente con reintentos, redacción y normalización de errores
src/mcp_server_for_ynab/models/: formas tipadas de YNAB, modelo de errores compartido, ayudas de milliunits
src/mcp_server_for_ynab/enriched/: flujos de trabajo de solo lectura de nivel superior construidos sobre clientes crudos
tests/: activos fuente de pruebas unitarias, de contrato, de integración y QA/Postman

Ejecútalo desde un clon:

git clone https://github.com/hs737/mcp-server-for-ynab
cd mcp-server-for-ynab
uv sync
cp .env.example .env    # then set YNAB_API_KEY

make smoke-stdio
make run-stdio
make run-http

Ejecuta las pruebas:

make test
make test-unit
make test-contract
make test-integration
make test-postman-operator

Dónde leer a continuación

Si estás:

conectando un cliente: Configuración del Cliente
nuevo en el repositorio: Arquitectura
agregando código: Contribuir, Estructura del Repositorio, Guía para Agentes
agregando o cambiando herramientas: Superficie de Herramientas
verificando comportamiento: Pruebas
trabajando en autenticación, manejo de errores o registro: Seguridad
publicando o agregando un canal de versiones: Distribución

Mapa completo: Índice de Documentación. También: Notas de Postman, Aviso Legal.

Estado Actual

La implementación actual utiliza Python 3.12, FastMCP del paquete oficial mcp, asyncio de extremo a extremo, httpx para llamadas salientes a YNAB, y los transportes integrados stdio y streamable HTTP.

Este es un servidor local de token de acceso personal. Un conector alojado o público no está implementado — eso incluye conectores personalizados de ChatGPT, que requieren un endpoint HTTPS remoto en lugar de un proceso local. La intención es que un runtime alojado viva en su propio repositorio, importando este paquete a través de su superficie de integración para que OAuth y las preocupaciones de aplicaciones públicas permanezcan fuera de aquí.

Si la arquitectura y la implementación alguna vez divergen, la fuente de verdad debería ser Arquitectura, actualizada para reflejar el código real.

Licencia

Licencia Apache 2.0. Ver LICENCIA y NOTICE.md.

Aviso legal

No estamos afiliados, asociados o de cualquier manera conectados oficialmente con YNAB o cualquiera de sus subsidiarias o afiliadas. El sitio web oficial de YNAB se puede encontrar en https://www.ynab.com.

Los nombres YNAB y You Need A Budget, así como nombres relacionados, marcas comerciales, marcas, emblemas e imágenes son marcas registradas de YNAB.