Datos y sincronización
Importes
Sección titulada «Importes»YNAB guarda cada importe como un número entero de miliunidades: 1,00 es 1000,
−12,34 es -12340. avenir-mcp convierte en la frontera y nunca muestra miliunidades al
agente:
| Sentido | Regla |
|---|---|
| YNAB → agente | miliunidades / 1000 |
| agente → YNAB | round(importe × 1000): 111,32 pasa a ser exactamente 111320 |
Sumas, diferencias y prorrateos se calculan en miliunidades y se convierten una sola vez: ningún error de redondeo crea ni pierde un céntimo. Los importes están en la moneda del plan; los gastos son negativos, las entradas positivas.
Hablar con YNAB
Sección titulada «Hablar con YNAB»client.py es el único módulo que llama a la API de YNAB:
| URL base | https://api.ynab.com/v1, o AVENIR_MCP_YNAB_URL |
| Autenticación | Authorization: Bearer <YNAB_API_KEY> en cada petición |
| Métodos | GET para leer; PATCH, POST y DELETE sobre transacciones, categorías y presupuestos mensuales |
| Errores | cualquier 4xx o 5xx vuelve como Error calling tool '<tool>': YNAB <status>: <detail>, con la explicación de YNAB |
plan_id acepta last-used, que YNAB resuelve como el último plan abierto.
Los planes, antes presupuestos
Sección titulada «Los planes, antes presupuestos»El registro de cambios de la API de YNAB indica que en la
versión 1.79.0, publicada el 5 de marzo de 2026, se cambió el nombre de /budgets por
/plans: la especificación ya solo documenta rutas /plans. avenir-mcp la sigue: su cliente llama a
/plans, y sus herramientas dicen list_plans y plan_id. La palabra budget se queda
donde YNAB la mantiene, para el dinero asignado a una categoría (budgeted, mostrado como
Assigned), de ahí set_category_budget y get_budget_vs_actual.
Las referencias de YNAB
Sección titulada «Las referencias de YNAB»- Documentación de la API de YNAB — endpoints, autenticación, límite de peticiones (en inglés)
- Especificación OpenAPI — la fuente de la página Cobertura de la API de YNAB
- Registro de cambios de la API de YNAB — versión 1.79.0, publicada el 5 de marzo de 2026:
/budgetsha pasado a denominarse/plans - Navigating Multiple Plans in YNAB
- How to Adjust Your Plan Settings
La copia local de las transacciones
Sección titulada «La copia local de las transacciones»La mayoría de las herramientas necesitan las transacciones del plan: encontrar lo pendiente, aprender del historial, comparar con el banco, prever. Descargarlo todo en cada llamada sería lento y gastaría la cuota de YNAB. avenir-mcp guarda una copia por plan, en memoria, y la actualiza con la sincronización incremental de YNAB:
- La primera carga pide todas las transacciones y guarda el
server_knowledgede YNAB, un contador de cambios. - La carga siguiente envía
last_knowledge_of_servery recibe solo lo que cambió desde entonces: transacciones nuevas, modificadas y borradas. - avenir-mcp las fusiona en su copia: una transacción modificada sustituye a la anterior, una borrada se elimina.
Con el id de un plan, la copia se actualiza por sincronización incremental.
Con last-used, que designa el último plan abierto en YNAB y puede cambiar de
una llamada a otra, las transacciones se cargan completas cada vez — sigue siendo una
sola petición — para no mezclar nunca dos planes. Con varios planes, pase
el id que da list_plans.
La copia vive tanto como el proceso del servidor. Las lecturas filtradas — por fecha o por categoría — no la usan.
El límite de peticiones de YNAB
Sección titulada «El límite de peticiones de YNAB»YNAB permite 200 peticiones por hora por token, en una ventana deslizante. Lo que cuesta cada herramienta, con la caché fría, se mide sobre el plan de demostración y se indica en su página de referencia:
| Coste | Herramientas |
|---|---|
| 0 | toda llamada rechazada por la validación (un mes mal formado, un nombre vacío…) |
| 1 | list_plans, list_accounts, list_category_groups, get_monthly_summary, get_age_of_money, get_category_balances, get_budget_vs_actual, get_underfunded_targets, get_debt_payoff_plan, approve_transactions, la vista previa de set_category_budget, la vista previa de move_money, la vista previa de flag_transactions, la vista previa de set_category_target |
| 2 | get_net_worth_trend, get_runway, get_debt_payoff_plan sin monthly_budget cuando falta un pago mínimo, reconcile_account, create_transactions, create_category, update_category, list_payees, la vista previa de rename_payee, undo_operation |
| 3 | get_runway con essential_groups, get_savings_rate, find_transactions, find_recurring_charges, list_scheduled_transactions, suggest_categories (una página entera), apply_categories, la vista previa de split_transaction |
| 4 | forecast_balance |
| 1 + N | get_spending_trends sobre N meses |
Aplicar una escritura confirmada añade su propia petición (un único PATCH agrupado, sea
cual sea el número de transacciones). Con la caché caliente, releer las transacciones
cuesta una pequeña petición incremental.
Cuando se agota la cuota, YNAB responde 429, y esa respuesta nunca se
reintenta: avenir-mcp devuelve … YNAB 429: … y no envía ninguna petición durante
10 minutos, o durante el número de segundos que indica la cabecera Retry-After de YNAB
cuando la respuesta la incluye (mantenido entre 1 minuto y 1 hora). avenir-mcp también se
detiene por sí mismo en 180 peticiones en la última hora, dejando el resto a otras
aplicaciones que usen el mismo token, e indica en cuántos minutos podrá salir la
siguiente petición. En ambos casos, el agente debe avisarle y no reintentar antes.
Cuando YNAB no responde
Sección titulada «Cuando YNAB no responde»Una lectura que falla de camino — un tiempo de espera agotado, una conexión rechazada, un
502, un 503 o un 504 — se envía de nuevo, tres veces en total, con una breve
espera que se duplica entre cada intento. Repetir una lectura no cambia nada, así que
solo le cuesta peticiones, y cada intento se descuenta de las 180 de la hora.
Una escritura es distinta. Una vez que un POST, un PATCH o un DELETE ha salido,
avenir-mcp nunca lo vuelve a enviar: YNAB puede haberlo aplicado y haber respondido
por una conexión que ya no existía, y una segunda copia crearía una segunda transacción o
un segundo cambio. El único fallo que vuelve a enviar una escritura es el que demuestra
que nunca salió, como una conexión rechazada.
Así, una escritura cuya respuesta nunca llegó termina en una respuesta que dice
exactamente eso: el cambio puede estar aplicado o no, y se le indica al agente que mire
con find_transactions o get_category_balances en lugar de repetirla. Una lectura que
nunca llegó a su destino dice, en cambio, que no se cambió nada y que se puede volver a
pedir en unos minutos.
Lo que nunca se guarda
Sección titulada «Lo que nunca se guarda»avenir-mcp no guarda ninguna copia en disco. Las transacciones viven en memoria mientras el servidor se ejecuta; el diario solo contiene identificadores, los importes asignados por un cambio de presupuesto o un movimiento entre categorías, el objetivo que restaurar y los dos nombres de un beneficiario renombrado; el token se queda en el entorno y nunca se registra.
Proyecto no oficial. «We are not affiliated, associated, or in any way officially connected with YNAB or any of its subsidiaries or affiliates. The official YNAB website can be found at https://www.ynab.com. The names YNAB and You Need A Budget, as well as related names, tradenames, marks, trademarks, emblems, and images are registered trademarks of YNAB.» No estamos afiliados, asociados ni conectados oficialmente de ninguna manera con YNAB ni con sus filiales o empresas afiliadas. El sitio web oficial de YNAB se encuentra en https://www.ynab.com. Los nombres YNAB y You Need A Budget, así como los nombres, nombres comerciales, marcas, emblemas e imágenes relacionados, son marcas registradas de YNAB. avenir-mcp se ofrece tal cual, sin garantía, y no es asesoramiento financiero. Aviso legal · Privacidad