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.
- Instalar uv, la herramienta que ejecuta avenir-mcp.
- Obtener un token de YNAB, el acceso de avenir-mcp a sus planes.
- Primer arranque a mano, una sola vez.
- Añadir avenir-mcp a su cliente.
- Comprobar que funciona con una primera pregunta.
- Permitir cambios, si quiere que el agente ordene por usted.
Lo que necesita
Sección titulada «Lo que necesita»| 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.
Instalar uv
Sección titulada «Instalar uv»En un terminal:
curl -LsSf https://astral.sh/uv/install.sh | shO, con Homebrew: brew install uv.
En PowerShell:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"O, con WinGet: winget install --id=astral-sh.uv -e.
Cierre y vuelva a abrir el terminal, y compruebe:
uv --versionMuestra 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.
Obtener un token de YNAB
Sección titulada «Obtener un token de YNAB»- Inicie sesión en YNAB en un navegador web, en app.ynab.com — las aplicaciones móviles no muestran los ajustes de desarrollador.
- Haga clic en su nombre arriba a la izquierda y luego en Account Settings.
- Abra Developer Settings.
- En Personal Access Tokens, haga clic en New Token, introduzca su contraseña de YNAB y pulse Generate.
- 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.
Instalar la extensión de Claude Desktop
Sección titulada «Instalar la extensión de Claude Desktop»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 DesktopEl 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.
-
Instale Claude Desktop, si aún no lo ha hecho, desde claude.ai/download, y ábralo una vez.
-
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.
-
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.mcpbde 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
.mcpbcon Claude Desktop. Si, por el contrario, Windows le pregunta con qué aplicación desea abrir el archivo, cierre esa ventana: los archivos.mcpbno tienen ninguna aplicación asociada, y al buscarclaude.exeno 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.
-
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.
-
Pegue su token en el campo YNAB personal access token, el del paso anterior.
Ctrl+Ven Windows y Linux,⌘+Ven 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. -
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.
-
Compruebe que está ahí. Settings → Extensions muestra ahora avenir-mcp for YNAB, activada.
-
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 |
Primer arranque a mano
Sección titulada «Primer arranque a mano»Antes de configurar un cliente, ejecute avenir-mcp una vez a mano. Así se descarga y se comprueba que arranca.
YNAB_API_KEY=su-token uvx avenir-mcp$env:YNAB_API_KEY = "su-token"; uvx avenir-mcpLa 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.
Añadir avenir-mcp a su cliente
Sección titulada «Añadir avenir-mcp a su cliente»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:
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.
La extensión es la vía corta, la que no pide un terminal: Instalar la extensión de Claude Desktop.
O a mano, si prefiere escribir usted mismo la configuración:
- Abra Claude Desktop y luego Settings → Developer → Edit Config. Se abre
claude_desktop_config.json:- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
- Si el archivo está vacío, pegue todo esto. Si ya lista servidores, añada solo el
bloque
"avenir-mcp": { … }dentro delmcpServersexistente, con una coma tras la entrada anterior.{"mcpServers": {"avenir-mcp": {"command": "uvx","args": ["avenir-mcp"],"env": { "YNAB_API_KEY": "su-token" }}}} - Guarde y cierre Claude Desktop por completo — ⌘Q en macOS, o desde el icono de la bandeja en Windows — y vuelva a abrirlo.
- Haga clic en el botón: Cursor le pide que confirme y, a continuación, añade
avenir-mcpa sus servidores. - Abra Cursor Settings → MCP, sustituya
su-tokenpor el token que ha copiado y compruebe queavenir-mcpestá activado.
O bien a mano: cree o abra ~/.cursor/mcp.json (todos los proyectos) o
.cursor/mcp.json en un proyecto, y añada:
{ "mcpServers": { "avenir-mcp": { "command": "uvx", "args": ["avenir-mcp"], "env": { "YNAB_API_KEY": "su-token" } } }}- Haga clic en el botón: VS Code le pide que confirme; a continuación, le solicita su token en un campo de contraseña y lo guarda en su propio almacén secreto.
- Úselo en Copilot Chat en modo Agent.
O bien a mano: cree .vscode/mcp.json en su espacio de trabajo. VS Code también
solicita el token en ese punto, por lo que el archivo nunca lo almacena: es fácil
añadir por error un archivo de un espacio de trabajo a un repositorio.
{ "inputs": [ { "type": "promptString", "id": "ynab-token", "description": "Token de acceso personal de YNAB", "password": true } ], "servers": { "avenir-mcp": { "type": "stdio", "command": "uvx", "args": ["avenir-mcp"], "env": { "YNAB_API_KEY": "${input:ynab-token}" } } }}A continuación, ejecute el comando MCP: List Servers, elija avenir-mcp y luego
Start Server.
- Abra
~/.gemini/settings.json(créelo si hace falta) y añada:{"mcpServers": {"avenir-mcp": {"command": "uvx","args": ["avenir-mcp"],"env": { "YNAB_API_KEY": "su-token" }}}} - Arranque
geminiy escriba/mcp:avenir-mcpaparece con sus herramientas. El modelo es el que usa Gemini CLI.
- Abra
~/.codex/config.toml(créelo si hace falta) y añada:[mcp_servers.avenir]command = "uvx"args = ["avenir-mcp"]env = { YNAB_API_KEY = "su-token" } - Arranque
codexy escriba/mcp:avenir-mcpaparece con sus herramientas. El modelo es el que usa Codex.
Para un modelo que se ejecuta en su propia máquina — vea Elegir un modelo.
- Haga clic en el botón: LM Studio le pide que confirme y, a continuación, añade
avenir-mcpa su archivomcp.json. - En LM Studio, abra la pestaña Program de la barra lateral derecha, luego Install → Edit mcp.json, y sustituya
su-tokenpor el token que ha copiado. - Guarde, cargue un modelo que admita llamadas a herramientas y abra un chat: LM Studio pregunta antes de cada llamada.
O bien, de forma manual: añada esto al mismo archivo mcp.json:
{ "mcpServers": { "avenir-mcp": { "command": "uvx", "args": ["avenir-mcp"], "env": { "YNAB_API_KEY": "su-token" } } }}Cualquier cliente MCP que arranque servidores por stdio funciona. Indíquele:
| Ajuste | Valor |
|---|---|
| comando | uvx |
| argumentos | avenir-mcp |
| entorno | YNAB_API_KEY = su token |
Para ejecutarlo en un contenedor, compile la imagen a partir del archivo Dockerfile
situado en la raíz del repositorio con el comando docker build -t avenir-mcp ., y, a
continuación, indique docker como comando en el cliente y
run -i --rm -e YNAB_API_KEY avenir-mcp como argumentos, de modo que el token se
transmita a través del entorno en lugar de a través de la línea de comandos.
Para los clientes que se conectan a una URL, vea Ejecutar por HTTP.
Comprobar que funciona
Sección titulada «Comprobar que funciona»claude mcp listavenir-mcp debe estar conectado:
avenir-mcp: uvx avenir-mcp - ✔ ConnectedDespués arranque claude y escriba /mcp: avenir-mcp muestra sus 19 herramientas.
Abra la lista de servidores MCP o de herramientas del cliente: avenir-mcp debe estar
activo, con 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:
[ { "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.
Permitir cambios
Sección titulada «Permitir 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.
Quite avenir-mcp y vuelva a añadirlo con la variable adicional:
claude mcp remove avenir-mcp --scope userclaude mcp add avenir-mcp --scope user \ --env YNAB_API_KEY=su-token \ --env AVENIR_MCP_WRITE=1 \ -- uvx avenir-mcpAñada la variable junto al token, guarde y reinicie el cliente:
"env": { "YNAB_API_KEY": "su-token", "AVENIR_MCP_WRITE": "1" }Añada la variable junto al token en ~/.codex/config.toml y reinicie Codex:
env = { YNAB_API_KEY = "su-token", AVENIR_MCP_WRITE = "1" }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.
Actualizar, quitar, revocar
Sección titulada «Actualizar, quitar, revocar»| 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 |
Siguiente
Sección titulada «Siguiente»- Su primera conversación: una visita guiada.
- Funciones: todo lo que avenir-mcp sabe hacer.
- Configuración: cada variable de entorno.
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