mcpField
A
avenir-mcp

avenir-mcp

Local
avenir-mcp.pages.devFinance4Updated 1d ago
RepositoryVisit website

About avenir-mcp

avenir-mcp is an unofficial MCP server for people who want an AI agent to inspect and plan a personal YNAB budget. It is read-only by default, and enabled changes require confirmation and can be undone.

Key features

  1. 01Monthly budget summaries
  2. 02Balance forecasting and debt payoff plans
  3. 03Transaction search and categorization suggestions
  4. 04Account reconciliation
  5. 05Preview, confirm, and undo budget changes

Use cases

  1. 01Find overspending categories for a month
  2. 02Estimate whether a balance will fall below zero
  3. 03Review pending transactions for categorization
  4. 04Move money between budget categories with an undo option

MCP support

Exposes YNAB budget-reading and planning tools to MCP clients. Write tools are not registered by default; when enabled, changes require confirmation and can be reversed with undo_operation.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "mathbeal-avenir": {
      "command": "uvx",
      "args": [
        "avenir-mcp"
      ],
      "env": {
        "YNAB_API_KEY": "<YNAB_API_KEY>",
        "AVENIR_MCP_WRITE": "<AVENIR_MCP_WRITE>"
      }
    }
  }
}
Run commanduvx avenir-mcp
Environment variables to set
YNAB_API_KEYSecretYour YNAB personal access token (YNAB > Account settings > Developer settings).
AVENIR_MCP_WRITESet to 1 to expose the write tools; read-only otherwise.

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
pypiavenir-mcp0.8.0

Tools

19

Saved tool list · updated 3d ago

ParameterTypeRequiredDescription
untilstringYesLast month to project, YYYY-MM, at most 24 months ahead.
plan_idstringYesYNAB plan id or 'last-used'.
one_offsanyNoExpected one-off amounts: {date YYYY-MM-DD, amount, label}; not those already scheduled in YNAB, which are counted.
account_idsanyNoAccounts to include (from list_accounts); default all open on-budget accounts.
monthly_incomeanyNoIncome expected each month, replacing the income found in the history (recurring or average) and scheduled in YNAB; default: what they show.
variable_monthlyanyNoMonthly spending besides recurring charges (negative); default: the last 3 months' average.

Details

From the project README

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.

Works with YNAB PyPI avenir-mcp on Glama Mentioned in Awesome MCP Servers licence quality MCP Inspector mutation docs YNAB API terms: self-checked coverage types docstrings code style python OpenSSF Best Practices last commit

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.

Download for Claude Desktop

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.

One conversation, in thirty seconds. Asked how the month is going and where the room is, the agent calls four read-only tools at the same time: Month summary, Every category, Budget vs spent and Three months. It answers that Restaurants is the only category over budget: 166.50 spent of 144.00 available (120.00 budgeted + 24.00 left from earlier months), 138.8 %, available −22.50; that its spending rose 113.70 → 119.90 → 166.50 over three months; and that 80.00 is left in Tennis and 411.90 in Groceries. It offers to cover the 22.50 from Tennis, which has nothing spent yet. The user answers “Cover it from Tennis.”, and move_money shows a preview that changes nothing: Tennis budgeted 80.00 → 57.50, Restaurants budgeted 120.00 → 142.50, available −22.50 → 0.00, exactly on budget, with a Cancel button, a Confirm button, and the reminder that nothing changes until you confirm and that any change can be undone.

▶ Watch the 20-second tour

get_net_worth_trend on the demo plan: over the last 18 months the debts shrink from 27,198 to 19,041 despite the car loan's interest, the assets grow, and the net worth rises from −24,038 to +1,230, with a dip for a car repair and another at Christmas.

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.
Asked how the budget is doing this month, the agent reads the month with two read-only tools and answers: one category over budget, Restaurants by 22.50, everything else on track. forecast_balance on the demo plan: the month-end balance rises from this month to three months ahead, with each month's lowest day and a yearly insurance payment scheduled next month.

📖 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.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.