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 presupuestos.
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.

Lo que necesita

	Por qué	Dónde conseguirlo
Una cuenta de YNAB	avenir-mcp lee y modifica sus presupuestos	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

macOS / Linux

En un terminal:

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

O, con Homebrew: brew install uv.

Windows

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

Obtener un token de YNAB

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.

Trate el token como una contraseña

Un token de acceso personal puede leer y modificar todos los presupuestos de su cuenta; YNAB no ofrece tokens de solo lectura. No lo pegue nunca en un chat con una IA, un archivo compartido, un issue o un repositorio. avenir-mcp nunca lo registra ni lo devuelve en una respuesta.

Primer arranque a mano

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

macOS / Linux

YNAB_API_KEY=su-token uvx avenir-mcp

Windows

$env: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.

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.

Claude Code

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.

Claude Desktop

1. 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
2. Si el archivo está vacío, pegue todo esto. Si ya lista servidores, añada solo el bloque "avenir-mcp": { … } dentro del mcpServers existente, con una coma tras la entrada anterior.

   {
     "mcpServers": {
       "avenir-mcp": {
         "command": "uvx",
         "args": ["avenir-mcp"],
         "env": { "YNAB_API_KEY": "su-token" }
       }
     }
   }

3. Guarde y cierre Claude Desktop por completo — ⌘Q en macOS, o desde el icono de la bandeja en Windows — y vuelva a abrirlo.

Cursor

1. 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" }
       }
     }
   }

2. Abra Cursor Settings → MCP y compruebe que avenir-mcp está activado.

VS Code

1. Cree .vscode/mcp.json en su espacio de trabajo:

   {
     "servers": {
       "avenir-mcp": {
         "type": "stdio",
         "command": "uvx",
         "args": ["avenir-mcp"],
         "env": { "YNAB_API_KEY": "su-token" }
       }
     }
   }

2. Ejecute el comando MCP: List Servers, elija avenir-mcp y luego Start Server.
3. Úselo en Copilot Chat en modo Agent.

Gemini CLI

1. 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" }
       }
     }
   }

2. Arranque gemini y escriba /mcp: avenir-mcp aparece con sus herramientas. El modelo es el que usa Gemini CLI.

Codex CLI

1. 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" }

2. Arranque codex y escriba /mcp: avenir-mcp aparece con sus herramientas. El modelo es el que usa Codex.

LM Studio

Para un modelo que se ejecuta en su propia máquina — vea Elegir un modelo.

1. En LM Studio, abra la pestaña Program de la barra lateral derecha, luego Install → Edit mcp.json, y añada:

   {
     "mcpServers": {
       "avenir-mcp": {
         "command": "uvx",
         "args": ["avenir-mcp"],
         "env": { "YNAB_API_KEY": "su-token" }
       }
     }
   }

2. Guarde, cargue un modelo que admita llamadas a herramientas y abra un chat: LM Studio pregunta antes de cada llamada.

Otros clientes

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 los clientes que se conectan a una URL, vea Ejecutar por HTTP.

«uvx no encontrado» en una aplicación de escritorio

Las aplicaciones gráficas no siempre ven el PATH de su terminal. Si el cliente no encuentra uvx, sustituya "uvx" por su ruta completa, que da which uvx (macOS, Linux) o where uvx (Windows) — por ejemplo "/Users/<usted>/.local/bin/uvx".

Comprobar que funciona

Claude Code

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 9 herramientas.

Otros clientes

Abra la lista de servidores MCP o de herramientas del cliente: avenir-mcp debe estar activo, con 9 herramientas.

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

list_plans

[
  {
    "id": "demo-budget",
    "name": "Demo household",
    "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

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.

Claude Code

Quite avenir-mcp y vuelva a añadirlo con la variable adicional:

claude mcp remove avenir-mcp --scope user
claude mcp add avenir-mcp --scope user \
  --env YNAB_API_KEY=su-token \
  --env AVENIR_MCP_WRITE=1 \
  -- uvx avenir-mcp

Configuraciones JSON

Añada la variable junto al token, guarde y reinicie el cliente:

"env": { "YNAB_API_KEY": "su-token", "AVENIR_MCP_WRITE": "1" }

Codex CLI (TOML)

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 20 herramientas en lugar de 11.

	Solo lectura (por defecto)	Con AVENIR_MCP_WRITE=1
Herramientas listadas	11	20
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

Si su cliente no puede preguntarle

Algunos clientes no pueden hacerle una pregunta (la elicitation de MCP). avenir-mcp da entonces al agente un código de un solo uso, y es el agente quien debe mostrarle los cambios y esperar su sí. En nuestra evaluación, un modelo de ocho, engañado por un memo colocado en una transacción, usó solo uno de esos códigos y luego deshizo su cambio. Para que solo usted pueda confirmar, añada AVENIR_MCP_REQUIRE_ELICITATION=1 si su cliente admite la elicitation: los códigos quedan desactivados.

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

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
Quitar	claude mcp remove avenir-mcp --scope user, o borre la entrada avenir-mcp de la configuración del cliente
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

• Su primera conversación: una visita guiada.
• Funciones: todo lo que avenir-mcp sabe hacer.
• Configuración: cada variable de entorno.