Unofficial MCP server for YNAB: read-only by default, every change previewed and undoable.
io.github.mathbeal/avenir-mcp (MCP) Server
Unofficial MCP server for YNAB that operates in read-only mode by default. It is designed so that any changes are previewed and can be undone, reflecting a workflow centered on safe modification rather than direct, irreversible updates.
π οΈ Key Features
Unofficial MCP server for YNAB
Read-only by default
Changes are previewed
Changes are undoable
π Use Cases
Access YNAB-related data in a non-mutating way
Safely review proposed updates before applying them
Roll back modifications using undo
β‘ Developer Benefits
Safer default behavior (read-only)
Supports review/preview of changes
Provides undo capability for reversibility
β οΈ Limitations
Unofficial integration for YNAB
Default is read-only, with changes requiring a preview/undo flow
Ask Claude β or any MCP client β about your plan in
plain words. Read-only by default; every change is previewed, confirmed by you, and can
be undone.
Install
You need a YNAB personal access token: YNAB β Account Settings β Developer Settings β
New Token.
Claude Desktop, no terminal: drop the file the button downloads onto Settings β
Extensions, then paste your token on that screen.
Claude Code, one command with your token in it:
bash
claude mcp add avenir-mcp --env YNAB_API_KEY=your-token -- uvx avenir-mcp
Both install it read-only. Cursor, LM Studio, VS Code, Windows, changes to your plan
(AVENIR_MCP_WRITE=1) and every option:
Install Β·
Configuration.
Missing a question? Have an idea? Tell us the question you would like to ask your budget
in Discussions β Ideas;
help with using avenir-mcp is in
Discussions β Q&A.
Never post a real amount, a real account or your token.
Why avenir-mcp
Tools for tasks, not endpoints. One tool classifies a month, one reconciles an account.
Read-only by default. The tools that change a plan are registered only if you enable them.
Preview, confirm, undo. A write waits for your yes; undo_operation reverts it.
Answers an agent can read. Currency units, typed answers, bank text treated as untrusted.
Verified. 100 % line and branch coverage, and a real agent on an invented plan: 25/25.
plugin/ is avenir-mcp as a Claude Code plugin: Claude Code asks for your token, keeps it
out of sight, and starts the server from the plugin's own locked environment. From a clone:
claude --plugin-dir plugin.
The plugin
What
runs
uv run --locked --projectthe plugin's folder, which starts the release plugin/pyproject.toml pins, and nothing else. No script of its own, no build step, no hook, no shell
contacts
pypi.org and files.pythonhosted.org, to install that release and the versions plugin/uv.lock pins, the first time; then api.ynab.com, with your token, as avenir-mcp always does
writes
the environment uv resolves inside the plugin's folder, and uv's own cache. Nothing elsewhere
changes in your plan
nothing. It starts avenir-mcp read-only: AVENIR_MCP_WRITE is not set, so the tools that change a plan are never registered
Development
bash
git clone https://github.com/mathbeal/avenir-mcp && cd avenir-mcp
uv sync
just check # lint, types, tests at 100 % coverage, vocabulary, lockfile
just docs-serve # the documentation, live
just evaluate # a real agent on the demo plan (uses your Claude plan)
Built and tested against YNAB's API v1.90.0; a weekly
YNAB API drift
check fails when YNAB publishes a new version. Self-checked on every change against
YNAB's API terms of 2025-05-28 (naming, attribution, YNAB's own image, a personal token
for its owner only, the hourly limit); a weekly job turns that badge red when they change.
Privacy Policy
avenir-mcp is a program you run yourself, not a service: its publisher runs no server and
receives none of your data. Your token is read from the environment, kept in memory as a
secret value and sent only to YNAB; your plan's data is fetched when a tool needs it and
returned to your agent, so the model provider behind your MCP client sees it too. What is
handled, how long it is kept and how to erase it:
https://avenir-mcp.pages.dev/avenir-mcp/project/privacy/.
Licence
MIT.
Unofficial project
We are not affiliated, associated, or in any way officially connected with YNAB or any of
its subsidiaries or affiliates. The official YNAB website can be found at
https://www.ynab.com. The names YNAB and You Need A Budget, as well as related names,
tradenames, marks, trademarks, emblems, and images are registered trademarks of YNAB. They
are named here only to say which service avenir-mcp works with. Listed by YNAB in its
Works with YNAB directory, among
third-party apps. Not endorsed by YNAB.
avenir-mcp is for personal use on your own machine, with your own YNAB token. Running
it as a public or shared server is not supported. It is provided as is, without warranty,
and is not financial advice: you remain responsible for the changes you confirm. See the
legal notice.
Install
Configuration
Environment variables
YNAB_API_KEYrequiredsecret
Your YNAB personal access token (YNAB > Account settings > Developer settings).
AVENIR_MCP_WRITE
Set to 1 to expose the write tools; read-only otherwise.