Configuración

avenir-mcp lee su configuración de variables de entorno, definidas en el bloque env de su cliente MCP o en el shell que lo arranca. No se lee nada más: no hay archivo de configuración.

Resumen

Variable	Por defecto	Significado
YNAB_API_KEY	— (obligatoria, o YNAB_API_KEY_FILE)	Su token de acceso personal de YNAB.
YNAB_API_KEY_FILE	sin definir	Un archivo con el token, usado cuando YNAB_API_KEY no está definida.
AVENIR_MCP_WRITE	sin definir: solo lectura	1 registra las herramientas que modifican su plan.
AVENIR_MCP_REQUIRE_ELICITATION	sin definir	1 solo acepta un sí dado en el cliente: sin códigos de confirmación.
AVENIR_MCP_TRANSPORT	stdio	stdio o http.
AVENIR_MCP_HOST	127.0.0.1	Dirección HTTP.
AVENIR_MCP_PORT	8103	Puerto HTTP.
AVENIR_MCP_HTTP_TOKEN	sin definir	Token que deben presentar los clientes HTTP; sin definir, se crea uno aleatorio en cada arranque.
AVENIR_MCP_JOURNAL	ver abajo	Archivo del diario, usado para anular operaciones.
XDG_STATE_HOME	~/.local/state	Dónde se guarda el diario por defecto.
AVENIR_MCP_CONFIDENCE_THRESHOLD	0.90	Confianza necesaria para sugerir una categoría.
AVENIR_MCP_LOG_LEVEL	WARNING	Nivel de los diagnósticos.
AVENIR_MCP_LOG_FORMAT	text	json escribe un objeto JSON por línea.
AVENIR_MCP_NO_UPDATE_CHECK	sin definir	1 detiene la comprobación diaria de una versión más reciente en PyPI.
AVENIR_MCP_YNAB_URL	https://api.ynab.com/v1	Dirección de la API.

Detalles

YNAB_API_KEY

Su token de acceso personal, en YNAB → Account Settings → Developer Settings. Sin él, cualquier herramienta que llame a YNAB falla con YNAB_API_KEY environment variable is not set. Da acceso completo de lectura y escritura a todos los planes de la cuenta.

YNAB_API_KEY_FILE

La ruta de un archivo que solo contiene el token, usado cuando YNAB_API_KEY no está definida: el token no aparece entonces en ninguna configuración de cliente MCP. El archivo debe ser legible solo por usted (chmod 600); si no, avenir-mcp lo rechaza y lo dice. En macOS, tras copiar el token:

mkdir -p ~/.config/avenir-mcp
(umask 077; pbpaste > ~/.config/avenir-mcp/ynab-token)   # el token que acaba de copiar

Después dé a YNAB_API_KEY_FILE la ruta completa del archivo, en el bloque env del cliente.

En macOS, el Llavero evita cualquier archivo: guarde el token una vez y deje que el cliente lo lea al arrancar.

security add-generic-password -a "$USER" -s avenir-ynab -w   # pide el token, oculto

"command": "/bin/sh",
"args": ["-c", "YNAB_API_KEY=$(security find-generic-password -s avenir-ynab -w) exec uvx avenir-mcp"]

macOS puede pedir una vez permiso para que security lea el elemento.

AVENIR_MCP_WRITE

Exactamente 1 registra las 13 herramientas de escritura. Cualquier otro valor, o ninguno, mantiene el servidor en solo lectura: esas herramientas no se listan ni se pueden llamar. Se lee una vez, al arrancar.

AVENIR_MCP_REQUIRE_ELICITATION

Exactamente 1: una escritura solo se aplica tras un sí dado en la ventana de confirmación del propio cliente. Los códigos de confirmación ni se emiten ni se aceptan, una pregunta cerrada cuenta como no, y un cliente que no sabe preguntar recibe un error. Úselo cuando el modelo podría transmitir un código sin preguntarle — vea Confirmación.

AVENIR_MCP_TRANSPORT, AVENIR_MCP_HOST, AVENIR_MCP_PORT

stdio (por defecto) para un cliente que arranca el servidor él mismo. http sirve HTTP streamable en http://{HOST}:{PORT}/mcp.

AVENIR_MCP_TRANSPORT=http AVENIR_MCP_PORT=9000 YNAB_API_KEY=… uvx avenir-mcp

Peligro

El tráfico es HTTP simple: mantenga AVENIR_MCP_HOST en 127.0.0.1. HOST y PORT sin prefijo se ignoran a propósito: los shells suelen dar a HOST el nombre de la máquina.

AVENIR_MCP_HTTP_TOKEN

Por HTTP, un secreto que cada petición debe llevar como Authorization: Bearer <token>; las demás reciben 401. Siempre obligatorio por HTTP: si no está definido, el servidor crea un token aleatorio en cada arranque y lo muestra una vez en stderr. Cree uno con openssl rand -hex 32. Se ignora por stdio. Sea cual sea el token, las cabeceras Host y Origin deben designar esta máquina. Vea Ejecutar por HTTP.

AVENIR_MCP_JOURNAL y XDG_STATE_HOME

El diario de las operaciones aplicadas. Por defecto: $XDG_STATE_HOME/avenir-mcp/journal.jsonl, o ~/.local/state/avenir-mcp/journal.jsonl cuando XDG_STATE_HOME no está definida. La carpeta se crea si hace falta. Vea Diario y deshacer.

AVENIR_MCP_CONFIDENCE_THRESHOLD

Un número entre 0 y 1: la parte del historial de un beneficiario que debe coincidir antes de sugerir una categoría. 0.90 sugiere menos a menudo y acierta más; 0.70 sugiere más. Se lee al arrancar. Vea Sugerencias.

AVENIR_MCP_LOG_LEVEL

DEBUG, INFO, WARNING (por defecto), ERROR. Los diagnósticos van a stderr. En INFO se registra cada llamada a herramienta y cada petición a YNAB — solo identificadores y cantidades, nunca beneficiarios, importes ni nombres; el token, nunca. DEBUG añade los mensajes de la biblioteca MCP, que pueden contener las propias peticiones.

AVENIR_MCP_LOG_FORMAT

text (por defecto): una línea legible por evento. json: un objeto JSON por línea, para un recolector de logs — vea Enviar los logs a un sistema de logs.

AVENIR_MCP_NO_UPDATE_CHECK

Sin definir (por defecto): al arrancar, como mucho una vez al día, el servidor pregunta a PyPI (https://pypi.org/pypi/avenir-mcp/json) por la última versión, esperando como mucho 1,5 segundos, y guarda la respuesta en latest-version.json bajo XDG_CACHE_HOME (~/.cache por defecto). Si hay una versión más reciente, una línea de sus instrucciones se lo dice al agente, que puede decírselo a usted, y la misma línea se registra como aviso. No se envía nada sobre usted ni sobre sus planes: es una petición anónima, que PyPI ve llegar desde su dirección. El servidor nunca se actualiza solo. 1: ninguna petición; DO_NOT_TRACK=1, o una ejecución de integración continua (CI=true), tiene el mismo efecto.

AVENIR_MCP_YNAB_URL

La dirección base de la API. Solo sirve para dirigir avenir-mcp a un sustituto, como hacen la evaluación y el generador de documentación con su servidor de plan de demostración. Debe empezar por https:// — http:// solo se acepta para 127.0.0.1 o localhost — porque cada petición lleva su token.

Argumentos de herramientas frecuentes

Argumento	Valores aceptados
plan_id	un id de plan de list_plans, o last-used
month	current, o el primer día de un mes: AAAA-MM-01
until	un mes, AAAA-MM, hasta 24 meses después
fechas	AAAA-MM-DD
importes	unidades monetarias; negativos para los gastos