MCP Server for YNAB

Servidor MCP 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.

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

Solo lectura de forma predeterminada. 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 anterior 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, 62 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 genérica stdio
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 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, incluido 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 fábrica:

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
"¿Esta cuenta coincide con el estado de cuenta y qué lo impide?"	reconcile_preview
"Aquí está el CSV del banco: ¿qué falta en cada lado?"	transactions_match_statement
"¿Hay retenciones de tarjeta en mi cuenta que nunca se publicaron?"	triage_pending_imports

Con YNAB_ALLOW_WRITES=1:

Categoriza las transacciones sin categorizar de la semana pasada y luego muéstrame qué 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 de herramientas actual agrupado por familia. Consulta Superficie de herramientas para ver el mapa completo.

Flujos de trabajo guiados

Siete 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, revisar y deshacer, y una auditoría de presupuesto de varios meses.

Cuatro recursos (ynab://guide/*) contienen el método YNAB, las reglas de seguridad de escritura, orientación sobre qué herramienta usar y cómo se comportan las cuentas de crédito. 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 predeterminado, lo que hace que plan_id sea opcional en la mayoría de las herramientas
YNAB_ALLOW_WRITES	No	Registra herramientas de escritura. Sin configurar significa solo lectura
YNAB_HISTORY_PATH	No	Archivo de historial de escrituras, predeterminado ~/.mcp-server-for-ynab/history.jsonl
YNAB_RATE_LIMIT_PER_HOUR	No	Presupuesto de solicitudes del lado del cliente, predeterminado 190 de los 200 de YNAB
YNAB_RATE_WARN_THRESHOLD	No	Advertir cuando queden esta cantidad de solicitudes, predeterminado 50
LOG_LEVEL	No	Verbosidad de registro, predeterminado 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 velocidad

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.

Cada respuesta de herramienta lleva requests_used_this_hour y requests_remaining, de la misma manera que una API HTTP devuelve X-RateLimit-Remaining: un agente se regula con un número que ya puede ver, donde pedirlo cuesta una llamada que no hará. overview_request_budget añade el límite, la ventana y cuándo se reabre un presupuesto agotado; ping responde si el servidor está activo. Ambos no cuestan nada.

La cuota pertenece al token de acceso, por lo que tus propias aplicaciones de YNAB también la consumen. El conteo aquí es lo que usó este servidor, que puede ser menos de lo que YNAB tiene disponible: cada error de límite de velocidad lo indica y lleva el tiempo de reapertura como marca de tiempo absoluta además de un retraso, para que un reintento programado no vuelva antes de tiempo.

Familias de Herramientas

62 herramientas de solo lectura, 84 con escrituras habilitadas, más 7 indicaciones guiadas y 4 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	Sobregiros, brechas de financiamiento, riesgos programados, financiamiento de tarjetas, auditorías de varios meses
reconcile	enriquecida	Comparación de estados de cuenta, coincidencia de exportaciones bancarias y finalización de una conciliación
history	enriquecida	Revisar y revertir escrituras hechas por este servidor
changes	enriquecida	Qué cambió desde un valor server_knowledge dado
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, rangos de varios meses, asignación por lotes
payees	cruda	Gestión de beneficiarios
payee_locations	cruda	Metadatos geográficos de beneficiarios, nicho/prioridad baja
transactions	cruda	CRUD de transacciones y activación de importación
scheduled_transactions	cruda	Gestión de transacciones programadas
money_movements	cruda	Datos de movimiento de dinero y movimiento de dinero entre categorías

Herramientas crudas son espejos cercanos de los endpoints de YNAB: úsalas para lecturas exactas y la mayoría de 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 ninguna herramienta enriquecida escribe a menos que su nombre y descripción lo digan.

Leer mucho presupuesto sin leer mucho JSON

Un solo mes de un plan real es alrededor de 60 KB de JSON, porque YNAB devuelve cada campo de objetivo de cada categoría, incluidas las ocultas. Revisar un año de esa manera no cabe en una ventana de contexto.

• months_get y categories_list toman compact=true, que devuelve seis campos por categoría en lugar de treinta: aproximadamente una cuarta parte del tamaño.
• months_range devuelve un rango completo como una matriz de categoría por mes, por lo que una revisión de veintiún meses es una sola llamada en lugar de veintiuna.
• category_groups_summary_by_month hace lo mismo a nivel de grupo, que es donde viven la mayoría de las preguntas de "¿está saludable?".
• changes_since informa qué cambió desde un valor server_knowledge, por lo que volver a verificar después de que el usuario edite su presupuesto cuesta una llamada pequeña.

Las herramientas de rango aún gastan una solicitud de YNAB por mes (no hay endpoint de rango), por lo que cada una indica su costo y el rango está limitado a 36 meses.

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, las 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 al mismo registro solo se componen correctamente en orden inverso. La reversión en sí 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 vuelven a leer 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.

Aplicando un plan, y moviendo dinero

La API de YNAB asigna dinero un mes-categoría a la vez, lo que hace que el plan de un mes sean treinta y cinco escrituras separadas y treinta y cinco entradas de historial separadas.

• months_assign_many aplica un mes completo en una sola llamada, registrado como una sola entrada, para que pueda deshacerse como la única decisión que fue.
• money_move mueve dinero disponible entre dos categorías — o hacia y desde Ready to Assign — leyendo los montos actuales y haciendo la aritmética, para que un saldo arrastrado no se confunda con el monto asignado.
• reconcile_apply finaliza una conciliación: marca las transacciones acordadas como conciliadas en una sola llamada masiva y publica el ajuste que cierra el residual, como una sola entrada que deshace ambos juntos.

Ambas herramientas de asignación también aceptan adjust_by en lugar de un total — "agrega $4,500 a esta categoría" sin que leas la cifra actual primero, ya que la leen de todos modos para registrar lo que una reversión restauraría. No es un delta atómico: la API de YNAB no tiene delta ni escritura condicional, por lo que el monto se lee y la suma se escribe, y una edición hecha en la aplicación entre esas dos llamadas se sobrescribe. Pasa expected_budgeted junto con él y la escritura se rechaza cuando el monto leído no es el que esperabas, por lo que un llamador que actúa sobre una cifra que ya se ha movido se detiene en lugar de sobrescribir. Eso es una verificación antes de la escritura, no una condición previa sobre ella: la brecha entre la lectura y la escritura permanece abierta, porque la ruta de YNAB no ofrece nada para cerrarla. De cualquier manera, la respuesta reporta previous_budgeted, budgeted y change, por lo que una escritura puede confirmarse sin una relectura.

Ninguna de ellas es atómica, porque YNAB no tiene límite de transacción. Cada una reporta lo que se aplicó y lo que falló, y un money_move a medio escribir aún se registra para que el dinero pueda devolverse.

Un límite que vale la pena conocer antes de conciliar a través de un agente: la API de YNAB no tiene una ruta que establezca el last_reconciled_at de una cuenta. Las transacciones realmente se marcan como conciliadas, pero la aplicación aún mostrará la fecha de la última conciliación realizada allí, y las herramientas lo dicen en lugar de reportar una cuenta como conciliada.

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. Nada se envía 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 Contribuyentes

Este repositorio está estructurado para que un contribuyente 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["MCPServer 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 MCPServer, 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 YNAB tipadas, modelo de error 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

Esos verifican que el servidor funcione. evals/ hace una pregunta diferente — si un asistente lo usa correctamente, que es donde han estado los fallos reales de este proyecto: un bloqueo por límite de tasa de un bucle que debería haber sido una sola llamada, una cuenta reportada como conciliada que YNAB aún mostraba como desactualizada. Esos casos se califican con un modelo en lugar de afirmarse, por lo que se ejecutan bajo demanda con claude plugin eval en lugar de en make check. Consulta evals/README.md.

Dónde leer a continuación

Si eres:

• conectando un cliente: Configuración del Cliente
• nuevo en el repositorio: Arquitectura
• agregando código: Contribuyendo, Estructura del Repositorio, Guía para Agentes
• agregando o cambiando herramientas: Superficie de Herramientas, Evaluaciones de Agentes
• verificando comportamiento: Pruebas
• trabajando en autenticación, manejo de errores o registro: Seguridad
• haciendo un lanzamiento, o agregando un canal: Distribución — las notas de lanzamiento son la anotación de la etiqueta, así que escríbelas antes de etiquetar

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

Estado Actual

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

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 las preocupaciones de OAuth y 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. Consulta LICENSE y NOTICE.md.

Aviso Legal

No estamos afiliados, asociados o de cualquier manera oficialmente conectados 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.