# Avenir MCP

> Avenir MCP is an open-source MCP server for finance and payments. Unofficial read-first MCP server for YNAB with previewed, undoable changes. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, macOS, Windows, Linux
- **Website:** https://avenir-mcp.pages.dev/avenir-mcp/
- **Repository:** https://github.com/mathbeal/avenir-mcp
- **MCP Registry name:** io.github.mathbeal/avenir-mcp
- **Categories:** finance and payments
- **Listing updated:** 2026-11-15

## About

Avenir-mcp is an open-source server for YNAB budgets, listed in YNAB's Works with YNAB directory but not endorsed by it. It exposes 17 task-shaped tools rather than raw API endpoints, so one tool classifies a month of transactions, reconciles an account or forecasts a balance. A local copy of your transactions refreshed by delta sync means most tools use one or two of YNAB's 200 requests per hour, and amounts come back in currency units rather than milliunits.

It is read-only by default: the thirteen write tools are not even listed until you set AVENIR_MCP_WRITE=1. Every change is previewed, confirmed by you in the client or with a one-time code, and journaled so it can be undone without overwriting later work. You supply a YNAB personal access token as YNAB_API_KEY.

Example questions include which category is overspent, whether the balance will go below zero before December, when debts will be paid off at 500 a month, and moving 30 from one category to another. It installs from PyPI with uvx or as a Claude Desktop extension, and the project reports 100% line and branch coverage.

## Features

- **Task-shaped tools:** 17 tools each handle a whole job such as reconciling an account.
- **Read-only by default:** Write tools stay hidden until you enable them.
- **Preview, confirm, undo:** Changes are previewed, confirmed and journaled for undo.
- **Debt payoff and forecasts:** Projects balances and debt payoff plans.
- **Quota-friendly sync:** Local transaction copy keeps YNAB requests low.
- **Typed outputs:** Currency units and field descriptions agents can read.

## Good for

- Find which budget category is overspent
- Forecast whether the balance dips below zero
- Categorise pending transactions
- Reconcile an account against bank balance
- Plan debt payoff with a monthly amount

## Install

### Claude Code (Terminal)

```sh
claude mcp add avenir-mcp --env YNAB_API_KEY='<YNAB_API_KEY>' -- uvx avenir-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "avenir-mcp": {
      "command": "uvx",
      "args": [
        "avenir-mcp"
      ],
      "env": {
        "YNAB_API_KEY": "<YNAB_API_KEY>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "avenir-mcp": {
      "command": "uvx",
      "args": [
        "avenir-mcp"
      ],
      "env": {
        "YNAB_API_KEY": "<YNAB_API_KEY>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "avenir-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "avenir-mcp"
      ],
      "env": {
        "YNAB_API_KEY": "<YNAB_API_KEY>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "avenir-mcp": {
      "command": "uvx",
      "args": [
        "avenir-mcp"
      ],
      "env": {
        "YNAB_API_KEY": "<YNAB_API_KEY>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "avenir-mcp": {
      "command": "uvx",
      "args": [
        "avenir-mcp"
      ],
      "env": {
        "YNAB_API_KEY": "<YNAB_API_KEY>"
      }
    }
  }
}
```

## Tools

- `get_budget_vs_actual`: Budgeted, spent and left for every category
- `get_monthly_summary`: Summary of a month
- `forecast_balance`: Forecasts the balance
- `get_debt_payoff_plan`: Plans debt payoff
- `suggest_categories`: Suggests categories for transactions
- `find_transactions`: Finds a transaction
- `reconcile_account`: Reconciles an account with the bank
- `move_money`: Moves money between categories
- `undo_operation`: Undoes an applied change

## FAQ

### Can it change my budget by default?

No. Write tools are not available until AVENIR_MCP_WRITE=1 is set.

### Can changes be reversed?

Yes. Applied changes are journaled and can be undone without overwriting later work.

### What credential is needed?

A YNAB personal access token supplied as YNAB_API_KEY.

### Is it official?

No. It is unofficial and not endorsed by YNAB.

### Is Avenir MCP free?

Yes. Avenir MCP is open source, so you can use and self-host it for free.

### How do I add Avenir MCP to Claude Code?

Run this command in your terminal: claude mcp add avenir-mcp --env YNAB_API_KEY='<YNAB_API_KEY>' -- uvx avenir-mcp

### What are the best alternatives to Avenir MCP?

The closest alternatives to Avenir MCP are Solana MCP by Vybe, Tapetide - Indian Stock Market MCP, Budget Tracker, Quantivex Research and Provyan.

## Alternatives

- [Solana MCP by Vybe](https://ai-powered.com/mcp/solana-mcp-by-vybe): Solana MCP by Vybe is an MCP server for finance and payments.
- [Tapetide - Indian Stock Market MCP](https://ai-powered.com/mcp/tapetide-indian-stock-market-mcp): Tapetide - Indian Stock Market MCP is a freemium MCP server for finance and payments.
- [Budget Tracker](https://ai-powered.com/mcp/budget-tracker-2): Budget Tracker is a freemium MCP server for finance and payments.
- [Quantivex Research](https://ai-powered.com/mcp/quantivex-research): Quantivex Research is a free MCP server for finance and payments.
- [Provyan](https://ai-powered.com/mcp/provyan): Provyan is a free MCP server for finance and payments.
- [TribuJus](https://ai-powered.com/mcp/tribujus): TribuJus is an open-source MCP server for legal and government.
- [L2WS](https://ai-powered.com/mcp/l2ws): L2WS is a paid MCP server for finance and payments.
- [Invoices](https://ai-powered.com/mcp/invoices): Invoices is a paid MCP server for files and documents.

---
Source: https://ai-powered.com/mcp/avenir-mcp
