Avenir Mcp

io.github.mathbealPublished by GitHub account mathbealv0.8.0Updated Oct 25, 2026

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

VerifiedSTDIODesktop onlyProductivity & WorkflowFinance

Overview

AI-generated overview

Unofficial YNAB server that lets an assistant read your budget plan, forecast balances, plan debt payoff and reconcile accounts, read-only by default.

What you can do
  • Summarize a month and spot overspent categories
  • Forecast balances and build debt payoff plans
  • Find transactions and suggest categories for pending ones
  • Reconcile an account against your bank balance
  • Move money between categories when write tools are enabled, with preview, confirmation and undo
When to use it
Use it when you keep your budget in YNAB and want to ask plain-language questions about your plan, check whether a spend fits, plan debt repayment, or tidy and reconcile transactions without opening the app.
Requirements
Runs locally over stdio from the PyPI package avenir-mcp (for example via uvx), so a Python/uv runtime is needed. Requires a YNAB personal access token supplied as the YNAB_API_KEY environment variable, and network access to YNAB's API. Write tools appear only when AVENIR_MCP_WRITE is set to 1.
Before you install
The YNAB_API_KEY token grants access to your YNAB plan and is sent to YNAB; keep it out of shared logs and posts. Budget data fetched by tools is returned to your assistant, so the model provider behind your MCP client sees it. Enabling AVENIR_MCP_WRITE exposes tools that change your plan; changes are previewed and undoable but you remain responsible for confirming them. Intended for personal use with your own token, not as a shared server, and it is not financial advice.

Installation

In SourceWeft

  1. Open Avenir Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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:

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.

[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

bash
git clone https://github.com/mathbeal/avenir-mcp && cd avenir-mcpuv syncjust check        # lint, types, tests at 100 % coverage, vocabulary, lockfilejust docs-serve   # the documentation, livejust 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.88.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.

Source: README.md at commit 77ab268

Tools

0
SourceWeft started this package once in an isolated sandbox, without credentials, to list its tools. That failed: the package did not install.

Version history

9
  1. v0.8.0LatestOct 25, 2026
  2. v0.7.1Oct 25, 2026
  3. v0.7.0Oct 22, 2026
  4. v0.6.0Oct 10, 2026
  5. v0.5.0Oct 2, 2026
  6. v0.4.0Oct 2, 2026
  7. v0.3.0Oct 1, 2026
  8. v0.2.1Oct 1, 2026
  9. v0.2.0Sep 30, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts