Ir al contenido

Instalación

Esta página le lleva de cero a avenir-mcp funcionando, en unos diez minutos. Cada paso termina con una comprobación: sabrá que ha funcionado antes de seguir.

  1. Instalar uv, la herramienta que ejecuta avenir-mcp.
  2. Obtener un token de YNAB, el acceso de avenir-mcp a sus planes.
  3. Primer arranque a mano, una sola vez.
  4. Añadir avenir-mcp a su cliente.
  5. Comprobar que funciona con una primera pregunta.
  6. Permitir cambios, si quiere que el agente ordene por usted.
Por qué Dónde conseguirlo
Una cuenta de YNAB avenir-mcp lee y modifica sus planes app.ynab.com
Un cliente MCP la aplicación con la que habla; es la que arranca avenir-mcp Claude Code, Claude Desktop, Cursor, VS Code…
uv descarga y ejecuta avenir-mcp, y el Python que necesita, en un entorno aislado el paso siguiente

No necesita instalar Python, clonar el repositorio ni crear un entorno virtual: uv se encarga de todo.

En un terminal:

Ventana de terminal
curl -LsSf https://astral.sh/uv/install.sh | sh

O, con Homebrew: brew install uv.

Cierre y vuelva a abrir el terminal, y compruebe:

Ventana de terminal
uv --version

Muestra una versión, por ejemplo uv 0.12.19. ¿Comando no encontrado? El instalador añade uv al PATH de los terminales nuevos: abra uno nuevo. Detalles en la documentación de uv.

  1. Inicie sesión en YNAB en un navegador web, en app.ynab.com — las aplicaciones móviles no muestran los ajustes de desarrollador.
  2. Haga clic en su nombre arriba a la izquierda y luego en Account Settings.
  3. Abra Developer Settings.
  4. En Personal Access Tokens, haga clic en New Token, introduzca su contraseña de YNAB y pulse Generate.
  5. Copie el token que aparece arriba: una larga cadena de letras, números y guiones. YNAB solo lo muestra una vez. Si lo pierde, cree otro y revoque el anterior.

Un solo archivo instala avenir-mcp, el Python sobre el que se ejecuta y los ajustes que necesita. En esta sección no hay terminal ni archivo de configuración, y ninguno de sus pasos es distinto en Windows, macOS o Linux, salvo donde lo diga.

Descargar para Claude Desktop

El archivo es siempre el de la última versión; la versión que se instala figura en su interior, y los pasos que se indican a continuación son los mismos independientemente de cuál sea.

  1. Instale Claude Desktop, si aún no lo ha hecho, desde claude.ai/download, y ábralo una vez.

  2. Descargue la extensión mediante el botón de arriba o a través de este enlace. Ocupa unos 17 kB y se guardará en su carpeta de descargas con el nombre avenir-mcp.mcpb.

    En Windows, Edge o Chrome pueden avisarle de que el archivo no se descarga habitualmente. Ese aviso trata de lo poco frecuente que es el archivo, no de lo que contiene: haga clic en los tres puntos junto a la descarga, y luego en Keep. Lo que sí puede comprobar del archivo está escrito en SECURITY.md.

  3. Arrastre el archivo hasta Settings → Extensions. Abra Claude Desktop y, a continuación, vaya a Settings → Extensions: en esa pantalla aparece una lista de las extensiones que tiene, y es ahí donde se instala el archivo. Seleccione el archivo avenir-mcp.mcpb de su carpeta de descargas o de la lista de descargas del navegador y arrástrelo hasta esa pantalla. Se abre el cuadro de diálogo de instalación.

    Hacer doble clic en el archivo también podría funcionar, si su sistema ya abre los archivos .mcpb con Claude Desktop. Si, por el contrario, Windows le pregunta con qué aplicación desea abrir el archivo, cierre esa ventana: los archivos .mcpb no tienen ninguna aplicación asociada, y al buscar claude.exe no aparece ningún resultado. En su lugar, arrastre el archivo hasta la pantalla Extensions.

    ¿Ninguna de las dos funciona? En esa misma pantalla, abra Advanced settings y, en la sección Extension Developer, seleccione Install Extension…; elija el archivo de su carpeta de descargas.

  4. Instálela. El cuadro de diálogo da el nombre de la extensión, avenir-mcp for YNAB, y dice lo que hace. Haga clic en Install.

  5. Pegue su token en el campo YNAB personal access token, el del paso anterior. Ctrl + V en Windows y Linux, ⌘ + V en macOS. El campo oculta lo que pega; Claude Desktop lo guarda donde su sistema guarda las contraseñas, y no queda escrito en ningún archivo que usted pueda abrir.

  6. Deje sin marcar la casilla Allow changes to your plans, y guarde. avenir-mcp responde preguntas y no cambia nada mientras esa casilla siga sin marcar. Puede marcarla más tarde, en el mismo sitio.

  7. Compruebe que está ahí. Settings → Extensions muestra ahora avenir-mcp for YNAB, activada.

  8. Pregúntele algo. En una conversación nueva, escriba: «Lista mis planes de YNAB.» Claude le pide permiso para la herramienta la primera vez; concédalo, y la respuesta da los nombres de sus planes. La primera respuesta tarda unos segundos más que las siguientes, mientras Claude Desktop descarga Python y avenir-mcp.

La instalación ha terminado. El resto de esta página trata de los demás clientes y de la instalación a mano; siga con su primera conversación, o con permitir cambios si quiere que el agente ordene por usted.

Para Haga
Cambiar el token, o permitir cambios Settings → Extensions → avenir-mcp for YNAB
Actualizar descargue de nuevo la extensión y arrástrela hasta la pantalla Settings → Extensions, sobre la que ya tiene instalada; el enlace siempre le lleva a la versión más reciente
Quitar quítela desde Settings → Extensions; el token se va con ella

Antes de configurar un cliente, ejecute avenir-mcp una vez a mano. Así se descarga y se comprueba que arranca.

Ventana de terminal
YNAB_API_KEY=su-token uvx avenir-mcp

La primera ejecución descarga avenir-mcp y Python: de unos segundos a un minuto. Después no se muestra nada y el comando no termina — es lo esperado: avenir-mcp espera a que un cliente le hable. Pulse Ctrl+C para detenerlo.

¿Aparece un error? Vea Solución de problemas.

Elija su cliente. Estas configuraciones son de solo lectura: avenir-mcp responde preguntas pero no cambia nada. Permitir cambios viene después. En Cursor, LM Studio y VS Code puede instalarlo con un solo clic, desde el botón situado en la parte superior de su pestaña.

En un terminal:

Ventana de terminal
claude mcp add avenir-mcp --scope user \
--env YNAB_API_KEY=su-token \
-- uvx avenir-mcp
Parte Significado
claude mcp add avenir-mcp registra un servidor MCP llamado avenir-mcp
--scope user para todos sus proyectos; sin él, solo para la carpeta actual
--env YNAB_API_KEY=… el entorno con el que arranca avenir-mcp
-- lo que sigue es el comando que arranca el servidor
uvx avenir-mcp ese comando

Claude Code guarda esto, token incluido, en ~/.claude.json, legible solo por usted.

Ventana de terminal
claude mcp list

avenir-mcp debe estar conectado:

avenir-mcp: uvx avenir-mcp - ✔ Connected

Después arranque claude y escriba /mcp: avenir-mcp muestra sus 19 herramientas.

Pregunte ahora, en una conversación nueva: «Lista mis planes de YNAB.» El agente llama a list_plans — su cliente puede pedirle permiso — y responde con sus nombres. Aquí, el plan de demostración usado en toda esta documentación:

list_plans
[
{
"id": "demo-budget",
"name": "Hogar de demostración",
"first_month": "2026-06-01",
"last_month": "2026-09-01"
}
]

avenir-mcp funciona. Siga con su primera conversación, o permita antes los cambios.

Para que el agente pueda clasificar transacciones, mover dinero entre categorías o conciliar cuentas, añada AVENIR_MCP_WRITE=1 al entorno de avenir-mcp.

Instalada desde la extensión: abra Settings → Extensions → avenir-mcp for YNAB, marque Allow changes to your plans, guarde, y reinicie Claude Desktop. La extensión pone la variable por usted, no hay nada que escribir.

El valor debe ser exactamente 1. Comprobación: el cliente lista ahora 32 herramientas en lugar de 19.

Solo lectura (por defecto) Con AVENIR_MCP_WRITE=1
Herramientas listadas 19 32
Clasificar, presupuestar, conciliar, crear — previsualizado, confirmado por usted, reversible
Si el agente entiende mal nada puede cambiar un cambio que usted confirmó, y que puede deshacer

Cada cambio se le muestra antes de aplicarse: vea Seguridad por diseño.

Para Haga
Actualizar uvx descarga las nuevas versiones por sí mismo de vez en cuando; fuércelo con uvx --refresh avenir-mcp. Para actualizar la extensión de Claude Desktop, debe descargarla de nuevo y arrastrarla a la pantalla Settings → Extensions, sobre la que ya tiene instalada
Quitar claude mcp remove avenir-mcp --scope user, o borre la entrada avenir-mcp de la configuración del cliente. La extensión se quita desde Settings → Extensions, token incluido
Limpiar el único archivo de avenir-mcp en su máquina es su diario, en ~/.local/state/avenir-mcp/
Revocar el token YNAB → Account Settings → Developer Settings → Revoke junto al token

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