avenir-mcp
by mathbeal
README.md
# avenir-mcp — an unofficial MCP server for YNAB
<!-- mcp-name: io.github.mathbeal/avenir-mcp -->
[](https://api.ynab.com/)
[](https://github.com/mathbeal/avenir-mcp/actions/workflows/ynab-terms.yml)
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 the badge red when YNAB changes its terms. Not reviewed or endorsed by YNAB.
[](https://github.com/mathbeal/avenir-mcp/actions/workflows/quality.yml)
[](https://github.com/mathbeal/avenir-mcp/actions/workflows/inspector.yml)
[](https://mathbeal.github.io/avenir-mcp/)
[](https://pypi.org/project/avenir-mcp/)
[](https://pypi.org/project/avenir-mcp/)
[](https://mathbeal.github.io/avenir-mcp/project/development/#the-checks)
[](https://mathbeal.github.io/avenir-mcp/project/development/#the-checks)
[](https://mathbeal.github.io/avenir-mcp/project/development/#the-checks)
[](https://mathbeal.github.io/avenir-mcp/project/development/#the-checks)
[](https://github.com/mathbeal/avenir-mcp/blob/main/LICENSE)
[](https://github.com/mathbeal/avenir-mcp/commits/main)
> 🇬🇧 **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](https://modelcontextprotocol.io) client — about your plan
in plain words: where the money went, what still needs a category, whether an account
matches the bank, when money would run out. Every change is previewed, confirmed by
you, and can be undone.
**📖 Documentation: <https://mathbeal.github.io/avenir-mcp/>**
[English](https://mathbeal.github.io/avenir-mcp/) · [Français](https://mathbeal.github.io/avenir-mcp/fr/) · [Español](https://mathbeal.github.io/avenir-mcp/es/) · [Deutsch](https://mathbeal.github.io/avenir-mcp/de/) · [Nederlands](https://mathbeal.github.io/avenir-mcp/nl/)
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mathbeal/avenir-mcp/main/.github/assets/conversation-dark.svg">
<img alt="Asked how the September budget is doing, the agent reads the month with two read-only tools and answers: one category over budget, Restaurants by 22.50, everything else on track." src="https://raw.githubusercontent.com/mathbeal/avenir-mcp/main/.github/assets/conversation-light.svg" width="720">
</picture>
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mathbeal/avenir-mcp/main/.github/assets/forecast-dark.svg">
<img alt="forecast_balance on the demo plan: the month-end balance rises from September to December, with each month's lowest day and a yearly insurance payment scheduled on 20 October." src="https://raw.githubusercontent.com/mathbeal/avenir-mcp/main/.github/assets/forecast-light.svg" width="720">
</picture>
Both come from the invented demo plan: a real reply of Claude Sonnet, and the forecast
the documentation shows.
> **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.
>
> 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](https://mathbeal.github.io/avenir-mcp/project/legal/).
## Why avenir-mcp
- **Tools for tasks, not endpoints.** Classify a month of transactions, reconcile an
account, forecast your balance: one tool each, not a wrapper of YNAB's API.
- **Read-only by default.** Tools that change your plan exist only when you enable
them.
- **Preview, confirm, undo.** Every write shows what will change and waits for your
yes; `undo_operation` reverts it.
- **Answers an agent can read.** Currency units, short typed answers, pagination,
errors that say what to fix, bank text treated as untrusted.
- **Verified.** 100 % line and branch coverage, and an evaluation where a real agent
works on an invented plan: 19/19 tasks.
## Install
You need [uv](https://docs.astral.sh/uv/) and a YNAB personal access token
(YNAB → Account Settings → Developer Settings → New Token).
[](https://insiders.vscode.dev/redirect/mcp/install?name=avenir-mcp&inputs=%5B%7B%22id%22%3A%22ynab_token%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22YNAB%20personal%20access%20token%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22avenir-mcp%22%5D%2C%22env%22%3A%7B%22YNAB_API_KEY%22%3A%22%24%7Binput%3Aynab_token%7D%22%7D%7D)
[](https://cursor.com/en/install-mcp?name=avenir-mcp&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJhdmVuaXItbWNwIl0sImVudiI6eyJZTkFCX0FQSV9LRVkiOiJ5b3VyLXRva2VuIn19)
One click installs avenir-mcp **read-only**: VS Code asks for your token in a password box and keeps it in its secret
storage; in Cursor, replace `your-token` in the server's settings. Add `AVENIR_MCP_WRITE=1` to allow changes.
Or by hand:
```bash
# Claude Code
claude mcp add avenir-mcp --env YNAB_API_KEY=your-token --env AVENIR_MCP_WRITE=1 -- uvx avenir-mcp
```
```jsonc
// Claude Desktop, Cursor: the mcpServers block of the client's configuration
{
"mcpServers": {
"avenir-mcp": {
"command": "uvx",
"args": ["avenir-mcp"],
"env": { "YNAB_API_KEY": "your-token", "AVENIR_MCP_WRITE": "1" }
}
}
}
```
Drop `AVENIR_MCP_WRITE` to stay read-only. Other clients and every option:
[Install](https://mathbeal.github.io/avenir-mcp/getting-started/install/) ·
[Configuration](https://mathbeal.github.io/avenir-mcp/reference/configuration/).
## What you can ask
| You ask | avenir-mcp |
|---|---|
| "Which category is overspent this month?" | `get_monthly_summary` — totals and overspent categories |
| "Categorise what is pending." | `suggest_categories`, then `apply_categories` after your yes |
| "Split this receipt: 81.15 groceries, 5.25 household." | `split_transaction` — one transaction across categories, after your yes |
| "Which transaction is my 86.40 receipt from the 12th?" | `find_transactions` — by dates, exact amount and account, categorised or not |
| "My bank shows 3,440.80. Does YNAB agree?" | `reconcile_account` — explains the gap, changes nothing until it matches |
| "Will I go below zero before December?" | `forecast_balance` — month by month, with its assumptions |
| "Move 30 from Tennis to Restaurants." | `set_category_budget`, previewed and undoable |
| "Undo that." | `undo_operation` |
Walk-throughs with real answers: [Use cases](https://mathbeal.github.io/avenir-mcp/guides/classify/).
Every tool, resource and prompt: [Reference](https://mathbeal.github.io/avenir-mcp/reference/tools/).
## 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)
```
Read [AGENTS.md](AGENTS.md) and [CONTRIBUTING.md](CONTRIBUTING.md) before opening a
pull request. Security reports: [SECURITY.md](SECURITY.md).
## Licence
MIT.
TDQS
A3.9/5.0
Scored across 12 tools
Disambiguation4/5
Most tools have clearly distinct purposes, and the descriptions explicitly disambiguate the trickiest pair (suggest_categories vs find_transactions, forecast_balance vs find_recurring_charges). The reporting cluster (get_category_balances, get_monthly_summary, get_budget_vs_actual, get_spending_trends) overlaps somewhat in scope, but each description steers to the right tool, so boundaries stay workable.
Naming Consistency4/5
All names are snake_case with a verb_ prefix, giving a largely predictable pattern. Minor inconsistency: read operations mix get_ (get_category_balances), list_ (list_accounts) and find_ (find_transactions) for similar listing behavior.
Tool Count5/5
12 tools is well within the sweet spot and each maps to a distinct task (plan discovery, reporting, transaction lookup, forecasting, categorization support). No filler tools and no topic is over-split.
Completeness3/5
The surface is read-heavy and self-referentially incomplete: suggest_categories tells the agent to 'assign with apply_categories' and list_category_groups tells it to pass a group id to create_category, but neither apply_categories nor create_category is present in this set. Read coverage (plans, accounts, categories, transactions, schedules, forecasts) is strong, but write/lifecycle operations are notably missing.
Maintenance
ActivityMaintained
ResponsivenessUnresponsive