Configuration

avenir-mcp reads its configuration from environment variables, set in your MCP client’s env block or in the shell that starts it. Nothing else is read: no configuration file.

Summary

Variable	Default	Meaning
YNAB_API_KEY	— (required, or YNAB_API_KEY_FILE)	Your YNAB personal access token.
YNAB_API_KEY_FILE	unset	A file holding the token, used when YNAB_API_KEY is unset.
AVENIR_MCP_WRITE	unset: read-only	1 registers the tools that change your plan.
AVENIR_MCP_REQUIRE_ELICITATION	unset	1 accepts only a yes given in the client: no confirmation codes.
AVENIR_MCP_TRANSPORT	stdio	stdio or http.
AVENIR_MCP_HOST	127.0.0.1	HTTP address.
AVENIR_MCP_PORT	8103	HTTP port.
AVENIR_MCP_HTTP_TOKEN	unset	Token HTTP clients must present; unset, a random one is made at each start.
AVENIR_MCP_JOURNAL	see below	Journal file, used by undo.
XDG_STATE_HOME	~/.local/state	Where the journal lives by default.
AVENIR_MCP_CONFIDENCE_THRESHOLD	0.90	Confidence needed to suggest a category.
AVENIR_MCP_LOG_LEVEL	WARNING	Diagnostics level.
AVENIR_MCP_LOG_FORMAT	text	json writes one JSON object per line.
AVENIR_MCP_NO_UPDATE_CHECK	unset	1 stops the daily check for a newer release on PyPI.
AVENIR_MCP_YNAB_URL	https://api.ynab.com/v1	API address.

Details

YNAB_API_KEY

Your personal access token, from YNAB → Account Settings → Developer Settings. Without it, any tool that calls YNAB fails with YNAB_API_KEY environment variable is not set. It grants full read and write access to every plan of the account.

YNAB_API_KEY_FILE

The path of a file that holds only the token, used when YNAB_API_KEY is unset: the token then appears in no MCP client configuration. The file must be readable by you only (chmod 600); otherwise avenir-mcp refuses it and says so. On macOS, after copying the token:

mkdir -p ~/.config/avenir-mcp
(umask 077; pbpaste > ~/.config/avenir-mcp/ynab-token)   # the token you just copied

Then give YNAB_API_KEY_FILE the file’s full path in the client’s env block.

On macOS, the Keychain avoids a file altogether: store the token once, then let the client read it at start-up.

security add-generic-password -a "$USER" -s avenir-ynab -w   # asks for the token, hidden

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

macOS may ask once to allow security to read the item.

AVENIR_MCP_WRITE

Exactly 1 registers the 13 write tools. Any other value, or none, keeps the server read-only: those tools are then neither listed nor callable. Read once, at start-up.

AVENIR_MCP_REQUIRE_ELICITATION

Exactly 1: a write applies only after the user says yes in the client’s own confirmation box. Confirmation codes are neither issued nor accepted, a dismissed question counts as no, and a client that cannot ask gets an error. Use it when the model might relay a code without asking you — see Confirmation.

AVENIR_MCP_TRANSPORT, AVENIR_MCP_HOST, AVENIR_MCP_PORT

stdio (default) for a client that starts the server itself. http serves streamable HTTP on http://{HOST}:{PORT}/mcp.

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

Danger

The traffic is plain HTTP: keep AVENIR_MCP_HOST on 127.0.0.1. HOST and PORT without the prefix are ignored on purpose: shells often set HOST to the machine’s name.

AVENIR_MCP_HTTP_TOKEN

Over HTTP, a secret every request must carry as Authorization: Bearer <token>; others get 401. Always required over HTTP: when it is unset, the server makes a random token at each start and prints it once on stderr. Create one with openssl rand -hex 32. Ignored over stdio. Whatever the token, the Host and Origin headers must name this machine. See Run over HTTP.

AVENIR_MCP_JOURNAL and XDG_STATE_HOME

The journal of applied operations. Default: $XDG_STATE_HOME/avenir-mcp/journal.jsonl, or ~/.local/state/avenir-mcp/journal.jsonl when XDG_STATE_HOME is unset. The folder is created when needed. See Journal and undo.

AVENIR_MCP_CONFIDENCE_THRESHOLD

A number between 0 and 1: the share of a payee’s history that must agree before a category is suggested. 0.90 suggests less often and is right more often; 0.70 suggests more. Read at start-up. See Suggestions.

AVENIR_MCP_LOG_LEVEL

DEBUG, INFO, WARNING (default), ERROR. Diagnostics go to stderr. At INFO, each tool call and each YNAB request is logged — identifiers and counts only, never payees, amounts or names; the token never is. DEBUG adds the MCP library’s own messages, which can contain the requests themselves.

AVENIR_MCP_LOG_FORMAT

text (default): one readable line per event. json: one JSON object per line, for a log collector — see Send logs to a log system.

AVENIR_MCP_NO_UPDATE_CHECK

Unset (default): at start-up, at most once a day, the server asks PyPI (https://pypi.org/pypi/avenir-mcp/json) for the latest release, waiting 1.5 seconds at most, and remembers the answer in latest-version.json under XDG_CACHE_HOME (~/.cache by default). When a newer release exists, a line in the server’s instructions tells the agent, which can tell you, and the same line is logged as a warning. Nothing about you or your plans is sent: it is one anonymous request, which PyPI sees coming from your address. The server never upgrades itself. 1: no request at all; DO_NOT_TRACK=1, or a CI run (CI=true), has the same effect.

AVENIR_MCP_YNAB_URL

The API’s base address. Only useful to point avenir-mcp at a stand-in, as the evaluation and the documentation generator do with their demo plan server. It must start with https:// — plain http:// is accepted only for 127.0.0.1 or localhost — because every request carries your token.

Tool arguments you will see often

Argument	Accepted values
plan_id	a plan id from list_plans, or last-used
month	current, or the first day of a month: YYYY-MM-01
until	a month, YYYY-MM, up to 24 months ahead
dates	YYYY-MM-DD
amounts	currency units; negative for spending