English Français العربية

io.github.mathbeal/avenir-mcp

Official registry Other

Unofficial MCP server for YNAB: read-only by default, every change previewed and undoable.

Source code Website Documentation

What can you do with io.github.mathbeal/avenir-mcp?

  • Understand a month — "Which category is overspent this month?" → get_monthly_summary
  • Prepare a spend — "Will I go below zero before December?" → forecast_balance
  • Pay off a debt — "When will my debts be paid off if I put 500 a month on them?" → get_debt_payoff_plan
  • Tidy the transactions — "Categorise what is pending." → suggest_categories, applied after your yes
  • Find one transaction — "Which transaction is my 86.40 receipt from the 12th?" → find_transactions
  • Reconcile an account — "My bank shows 3,440.80. Does YNAB agree?" → reconcile_account
  • Change something — "Move 30 from Tennis to Restaurants." → move_money, previewed, confirmed, and undone by undo_operation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

PYPI package avenir-mcp
Claude Code 
claude mcp add avenir-mcp -e 'YNAB_API_KEY=<your ynab_api_key>' -e 'AVENIR_MCP_WRITE=<AVENIR_MCP_WRITE>' -- uvx avenir-mcp==0.8.0
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "avenir-mcp": {
            "command": "uvx",
            "args": [
                "avenir-mcp==0.8.0"
            ],
            "env": {
                "YNAB_API_KEY": "<your ynab_api_key>",
                "AVENIR_MCP_WRITE": "<AVENIR_MCP_WRITE>"
            }
        }
    }
}

Environment variables

  • YNAB_API_KEY required secret Your YNAB personal access token (YNAB > Account settings > Developer settings).
  • AVENIR_MCP_WRITE Set to 1 to expose the write tools; read-only otherwise.

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. avenir-mcp: an unofficial MCP server for YNAB
  2. Install
  3. What you can ask
  4. Why avenir-mcp
  5. Claude Code plugin
  6. Development
  7. Privacy Policy
  8. Licence
  9. Unofficial project

avenir-mcp: an unofficial MCP server for YNAB

🇬🇧 avenir-mcp (avenir is French for the future) lets an AI agent read your YNAB plan and help you plan what comes next.

🇫🇷 avenir-mcp permet à un agent IA de lire votre plan YNAB et de vous aider à préparer la suite.

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:

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.

▶ Watch the 20-second tour

Both come from an invented demo plan, replayed by python -m docsgen: every figure is what avenir-mcp answers today.

What you can ask

  • Understand a month — "Which category is overspent this month?" → get_monthly_summary
  • Prepare a spend — "Will I go below zero before December?" → forecast_balance
  • Pay off a debt — "When will my debts be paid off if I put 500 a month on them?" → get_debt_payoff_plan
  • Tidy the transactions — "Categorise what is pending." → suggest_categories, applied after your yes
  • Find one transaction — "Which transaction is my 86.40 receipt from the 12th?" → find_transactions
  • Reconcile an account — "My bank shows 3,440.80. Does YNAB agree?" → reconcile_account
  • Change something — "Move 30 from Tennis to Restaurants." → move_money, previewed, confirmed, and undone by undo_operation

Every tool, with a real answer: Reference · Use cases.

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.

📖 Documentation: https://avenir-mcp.pages.dev/avenir-mcp/ · English · Français · Español · Deutsch · Nederlands

Claude Code plugin

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 pluginWhat
runsuv run --locked --project the 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
contactspypi.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
writesthe environment uv resolves inside the plugin's folder, and uv's own cache. Nothing elsewhere
changes in your plannothing. It starts avenir-mcp read-only: AVENIR_MCP_WRITE is not set, so the tools that change a plan are never registered

Development

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)

Read AGENTS.md and CONTRIBUTING.md before opening a pull request. Security reports: SECURITY.md. Also: ARCHITECTURE.md, ROADMAP.md, GOVERNANCE.md and the code of conduct.

Built and tested against YNAB's API v1.87.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.

Frequently asked questions

What is io.github.mathbeal/avenir-mcp?

Unofficial MCP server for YNAB: read-only by default, every change previewed and undoable.

How do I install io.github.mathbeal/avenir-mcp?

It runs on your machine. In Claude Code: claude mcp add avenir-mcp -e 'YNAB_API_KEY=<your ynab_api_key>' -e 'AVENIR_MCP_WRITE=<AVENIR_MCP_WRITE>' -- uvx avenir-mcp==0.8.0. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.mathbeal/avenir-mcp need an API key?

Yes. It expects YNAB_API_KEY, which you set in its configuration.

Is io.github.mathbeal/avenir-mcp open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.mathbeal/avenir-mcp?

It is published by mathbeal. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.