avenir-mcp — an unofficial MCP server for YNAB

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

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

Ask Claude — or any MCP client — about your budget 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/

Unofficial project. We are not affiliated, associated, or in any way officially connected with YNAB or any of its subsidiaries or affiliates. YNAB and You Need A Budget are registered trademarks of YNAB, 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.

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 budget 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: 17/17 tasks.

Install

You need uv and a YNAB personal access token (YNAB → Account Settings → Developer Settings → New Token).

# Claude Code
claude mcp add avenir-mcp --env YNAB_API_KEY=your-token --env AVENIR_MCP_WRITE=1 -- uvx avenir-mcp

// 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 · Configuration.

What you can ask

Walk-throughs with real answers: Use cases. Every tool, resource and prompt: Reference.

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 budget (uses your Claude plan)

Read AGENTS.md and CONTRIBUTING.md before opening a pull request. Security reports: SECURITY.md.

Licence

MIT.