Troubleshooting

Connection

My client does not show avenir-mcp’s tools

1. Check the server is connected: claude mcp list, or your client’s MCP panel.
2. Run uvx avenir-mcp in a terminal. It should wait silently for a client; an error printed there is the one your client hides.
3. Restart the client after editing its configuration.
4. Check uv is on the PATH your client sees. Graphical applications may not see the PATH of your shell: give the full path to uvx in the configuration.

The tools that change my budget are missing

avenir-mcp is read-only unless its environment contains AVENIR_MCP_WRITE=1 — exactly 1. Restart the server after changing it.

ModuleNotFoundError: avenir_mcp in a folder synced by iCloud Drive

iCloud can mark files as hidden, and recent Python versions skip hidden .pth files, which breaks editable installs. Keep the virtual environment outside the synced folder: UV_PROJECT_ENVIRONMENT=~/.local/share/avenir-mcp/venv uv sync.

YNAB

YNAB 401

The token is wrong or was revoked. Create a new one in YNAB’s Developer Settings and update YNAB_API_KEY.

YNAB 404

A budget, account, category or month that YNAB does not know. Ids come from list_plans, list_accounts, list_category_groups or get_category_balances; months must exist in the budget.

YNAB 429

The 200 requests per hour are spent. Wait a few minutes; later calls are cheap thanks to delta sync. See Data and sync.

Writes

The agent keeps answering confirmation_required

Your client cannot show a confirmation box, so avenir-mcp returned a preview and a code. Tell the agent you agree: it calls again with the code. A code lasts 10 minutes and works once; after a server restart, ask for a new preview.

The budget changed between the preview and the answer

Something changed a transaction between the preview and your answer — you in YNAB, an import, another agent. Ask again: the new preview reflects the current state.

Nothing to undo

No operation of this budget is still in effect in this machine’s journal: it was already undone, made elsewhere, or the journal file changed. See Journal and undo.

Diagnostics

Where do I see what the server does?

Set AVENIR_MCP_LOG_LEVEL=INFO (each call and request) or DEBUG (everything). Diagnostics go to stderr, which your client keeps in its MCP logs — in Claude Code, claude --debug shows them. stdout belongs to the protocol.

Every message a tool can return is listed in the error catalogue.