actual-budget-mcp

Talk to your budget. An MCP server that connects Actual Budget to Claude — ask where the money went, get real analysis back, and let it write without holding your breath.

Features

• Real analysis, not just lookups - Projections, category trends, budget vs actual, and month summaries
• Writes you can trust - Every delete previews what it will remove and waits for you to confirm; ACTUAL_READ_ONLY=1 hides the write tools from the model entirely (Safety)
• Multi-currency that survives reality - Splits and residual reconciliation, not just a currency symbol
• Recovers from an out-of-sync budget - repair_sync rebuilds the local sync state when @actual-app/api and your server disagree, the failure that otherwise leaves every tool erroring
• Ask about your budget in plain language - "How much did I spend on food this month?" or "Am I over budget on anything?"
• Create and manage transactions - Add expenses, transfers, and edits without opening the app
• Manage categories, payees, and rules - Full CRUD without opening the app
• Use names, not IDs - Say "Cartera" instead of a1b2c3d4-..., with helpful suggestions if ambiguous
• Natural dates in English and Spanish - "last month", "este mes", "hace 3 meses", "yesterday"
• Clean formatted output - Aligned tables and clear summaries, not raw JSON
• Clear error messages - If something's wrong, you'll know exactly what to fix

Does it work with local models?

Yes. This is an MCP server, so it works with any client that speaks MCP, and the model behind that client is the client's business, not this server's. Claude Desktop, Claude Code, Cursor and VS Code are the ones documented below because they are the ones people ask about, but anything that can run an MCP client, including a local setup pointed at Ollama or LM Studio, talks to it the same way.

Your budget data goes to whatever model your client uses. If that matters to you, and for a lot of people running Actual it does, a local model keeps it on your machine.

Prerequisites

• Actual Budget server running (local or remote)
• Node.js 20 or higher (see Node.js requirement)

Quick Start

The fastest way to get started - copy this into Claude Code or Claude Desktop:

Install the actual-budget-mcp MCP server from npm (https://github.com/henfrydls/actual-budget-mcp).
Configure it with these credentials:
    - My Actual Budget server: http://localhost:5006
    - Password: YOUR_PASSWORD
    - Budget ID: YOUR_BUDGET_ID

Claude will configure everything for you.

Installation

Option 1: Claude Code (one command)

claude mcp add actual-budget-mcp -e ACTUAL_SERVER_URL=http://localhost:5006 -e ACTUAL_PASSWORD=your-password -e ACTUAL_BUDGET_ID=your-budget-id -- npx -y actual-budget-mcp

Option 2: Claude Desktop

Add this to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "actual-budget-mcp": {
      "command": "npx",
      "args": ["-y", "actual-budget-mcp"],
      "env": {
        "ACTUAL_SERVER_URL": "http://localhost:5006",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_BUDGET_ID": "your-budget-sync-id"
      }
    }
  }
}

Option 3: Cursor

Go to Cursor Settings > MCP > Add new MCP server and add:

{
  "mcpServers": {
    "actual-budget-mcp": {
      "command": "npx",
      "args": ["-y", "actual-budget-mcp"],
      "env": {
        "ACTUAL_SERVER_URL": "http://localhost:5006",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_BUDGET_ID": "your-budget-sync-id"
      }
    }
  }
}

Option 4: VS Code (GitHub Copilot)

Add this to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "actual-budget-mcp": {
        "command": "npx",
        "args": ["-y", "actual-budget-mcp"],
        "env": {
          "ACTUAL_SERVER_URL": "http://localhost:5006",
          "ACTUAL_PASSWORD": "your-password",
          "ACTUAL_BUDGET_ID": "your-budget-sync-id"
        }
      }
    }
  }
}

Option 5: Docker

The image speaks stdio like every other option, so your client starts the container and owns its lifetime:

{
  "mcpServers": {
    "actual-budget-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--add-host=host.docker.internal:host-gateway",
        "-v", "actual-budget-mcp-data:/data",
        "-e", "ACTUAL_SERVER_URL",
        "-e", "ACTUAL_PASSWORD",
        "-e", "ACTUAL_BUDGET_ID",
        "ghcr.io/henfrydls/actual-budget-mcp:latest"
      ],
      "env": {
        "ACTUAL_SERVER_URL": "http://host.docker.internal:5006",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_BUDGET_ID": "your-budget-sync-id"
      }
    }
  }
}

Two things that bite everyone once:

• Inside the container, localhost is the container. Your Actual server is not there. host.docker.internal (with the --add-host flag above, which is what makes it resolve on Linux) reaches the host instead.
• Mount /data. That is the budget cache. Without a volume, every start re-downloads your entire budget from the server.

Option 6: From source (for contributors)

git clone https://github.com/henfrydls/actual-budget-mcp.git
cd actual-budget-mcp
npm install
cp .env.example .env   # Edit with your credentials
npm run build
npm run test:connection # Verify it works

Verify your setup

--verify reads the environment of the shell you run it in, and the install options above put your credentials in your MCP client's configuration instead. So set them for the command:

ACTUAL_SERVER_URL=http://localhost:5006 \
ACTUAL_PASSWORD=your-password \
ACTUAL_BUDGET_ID=your-sync-id \
npx -y actual-budget-mcp --verify

It connects, downloads the budget and prints how many accounts and category groups it found. Running it without those variables reports them as missing, which is about the command, not about your install.

After changing your client's configuration, restart the client. Claude Desktop, Claude Code and the rest read MCP configuration at startup and will not pick up an edit until they are restarted.

Configuration

Finding your Budget ID

1. Open Actual Budget
2. Open Settings: click the arrow next to your budget name, or use the sidebar, More, then Settings
3. Click Show advanced settings
4. Copy the Sync ID

Take the Sync ID, not the Budget ID. Actual shows both, one under the other, and they are both UUIDs. ACTUAL_BUDGET_ID wants the one labelled Sync ID, despite the name of the variable. Using the other one gives you Budget "..." not found on the server, which reads as though you mistyped it when the value was simply the wrong field.

If Sync ID shows (none), that budget has never been synced to a server. This server talks to Actual through its sync server, so a local-only budget cannot be used until you sync it.

Safety

Two things protect your budget from an agent acting on a vague instruction.

Deletes preview before they delete

Every delete tool refuses to destroy anything on the first call. It reports what would be lost and stops there. Deleting takes a second, deliberate call:

delete_category(category: "Groceries")
  → preview: transactions affected, budget and rollover warning. Nothing deleted.

delete_category(category: "Groceries", confirm: true, confirm_name: "Groceries")
  → deleted

Tools that find their target by name — delete_account, delete_category, delete_category_group, delete_payee — also require confirm_name with the exact name. That is where deleting the wrong thing actually happens: asking for "Adicionales" can resolve to "Ingresos Adicionales". Tools that take an exact id — delete_transaction, delete_rule — need only confirm: true.

Read-only mode

Set ACTUAL_READ_ONLY=1 and the server exposes only the 15 read, analysis and repair tools. The write tools are not registered at all, so they never appear in tool discovery — an agent cannot be talked into calling something it cannot see.

repair_sync stays available on purpose: it repairs sync state rather than budget data, and hiding it would leave a desynced budget with no way to recover.

Writes are enabled by default. Read-only is opt-in.

Tools (37)

Read (9)