Solución de problemas

Conexión

Mi cliente no muestra las herramientas de avenir-mcp

1. Compruebe que el servidor está conectado: claude mcp list, o el panel MCP de su cliente.
2. Ejecute uvx avenir-mcp en un terminal. Debe esperar a un cliente en silencio; un error mostrado allí es el que su cliente oculta.
3. Reinicie el cliente tras editar su configuración.
4. Compruebe que uv está en el PATH que ve su cliente. Las aplicaciones gráficas no siempre ven el PATH de su shell: indique la ruta completa de uvx en la configuración.

Faltan las herramientas que modifican mi presupuesto

avenir-mcp está en solo lectura salvo que su entorno contenga AVENIR_MCP_WRITE=1 — exactamente 1. Reinicie el servidor tras cambiarlo.

ModuleNotFoundError: avenir_mcp en una carpeta sincronizada por iCloud Drive

iCloud puede marcar archivos como ocultos, y las versiones recientes de Python ignoran los archivos .pth ocultos, lo que rompe las instalaciones editables. Mantenga el entorno virtual fuera de la carpeta sincronizada: UV_PROJECT_ENVIRONMENT=~/.local/share/avenir-mcp/venv uv sync.

YNAB

YNAB 401

El token es incorrecto o fue revocado. Cree uno nuevo en los Developer Settings de YNAB y actualice YNAB_API_KEY.

YNAB 404

Un presupuesto, cuenta, categoría o mes que YNAB no conoce. Los ids vienen de list_plans, list_accounts, list_category_groups o get_category_balances; los meses deben existir en el presupuesto.

YNAB 429

Se han agotado las 200 peticiones por hora. Espere unos minutos; las llamadas siguientes cuestan poco gracias a la sincronización incremental. Vea Datos y sincronización.

Escrituras

El agente responde una y otra vez confirmation_required

Su cliente no sabe mostrar un cuadro de confirmación, así que avenir-mcp devolvió una vista previa y un código. Diga al agente que está de acuerdo: vuelve a llamar con el código. Un código dura 10 minutos y sirve una vez; tras reiniciar el servidor, pida una nueva vista previa.

The budget changed between the preview and the answer

Algo cambió una transacción entre la vista previa y su respuesta — usted en YNAB, una importación, otro agente. Vuelva a pedirlo: la nueva vista previa refleja el estado actual.

Nothing to undo

Ninguna operación de este presupuesto sigue vigente en el diario de esta máquina: ya se deshizo, se hizo en otro lugar, o el archivo del diario cambió. Vea Diario y deshacer.

Diagnósticos

¿Dónde veo lo que hace el servidor?

Defina AVENIR_MCP_LOG_LEVEL=INFO (cada llamada y petición) o DEBUG (todo). Los diagnósticos van a stderr, que su cliente guarda en sus registros MCP — en Claude Code, claude --debug los muestra. stdout pertenece al protocolo.

Cada mensaje que puede devolver una herramienta figura en el catálogo de errores.