actual-budget-mcp

Talk to your budget. An MCP server that connects Actual Budget to Claude, so you can ask questions, create transactions, and analyze spending in natural conversation.

Features

• 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

• Get spending insights - Projections, trends, and budget vs actual comparisons

• 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

Related MCP server: YNAB MCP Server

Prerequisites

• Actual Budget server running (local or remote)

• Node.js 22 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: 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

After installing, you can verify the connection works:

npx -y actual-budget-mcp --verify

This will connect to your Actual Budget server and confirm everything is configured correctly.

Configuration

Finding your Budget ID

1. Open Actual Budget

2. Go to Settings (gear icon)

3. Click Show advanced settings

4. Copy the Sync ID

Tools (32)

Read (9)

get_budget_month - month (optional): YYYY-MM or natural language ("this month", "last month", "enero 2025")

get_transactions - account (optional): account name | start_date / end_date (optional): YYYY-MM-DD or natural language | category (optional): category name | payee (optional): payee name | min_amount / max_amount (optional): filter by amount | limit (optional, default 50)

get_category_balance - category (required): category name or ID | months (optional, default 3): months to look back

get_budget_summary - month (optional): YYYY-MM or natural language

balance_history - account (required): account name or ID | start_date (optional, default 3 months ago) | end_date (optional, default today)

Analysis (5)

budget_vs_actual - month (optional): YYYY-MM or natural language | group (optional): filter by category group

spending_projection - month (optional): YYYY-MM or natural language

category_trends - category (optional): specific category or top spending if omitted | months (optional, default 6)

spending_by_category - start_date / end_date (optional): date range | include_income (optional, default false) | limit (optional, default 20)

monthly_summary - months (optional, default 3): number of months to show

Write — Transactions (7)

create_transaction - account (required): account name | amount (required): negative for expenses, positive for income | payee (optional) | category (optional) | date (optional) | notes (optional) | cleared (optional)

update_transaction - transaction_id (required) | amount, payee, category, date, notes, cleared (all optional)

delete_transaction - transaction_id (required)

update_budget_amount - category (required) | amount (required) | month (optional)

recategorize_transaction - transaction_id (required) | category (required)

create_transfer - from_account (required) | to_account (required) | amount (required) | date (optional) | notes (optional)

run_bank_sync - account (optional): sync specific account or all if omitted

Write — Categories (6)

create_category - name (required) | group (required): group name or ID

update_category - category (required): name or ID | name (optional): new name | hidden (optional): true/false

delete_category - category (required) | transfer_to (optional): category to move transactions to

create_category_group - name (required)

update_category_group - group (required): name or ID | name (optional): new name | hidden (optional): true/false

delete_category_group - group (required) | transfer_to (required): category for orphaned transactions

Write — Payees & Rules (5)

create_payee - name (required)

update_payee - payee (required): name or ID | name (required): new name

delete_payee - payee (required): name or ID

create_rule - condition_field (required): payee, category, amount, notes | condition_op (required): is, contains, oneOf, gt, lt, etc. | condition_value (required) | action_field (required): category, payee, notes | action_value (required) | stage (optional)

delete_rule - rule_id (required)

Prompts

Built-in prompt templates that guide Claude through multi-step financial analysis:

Use them in Claude Desktop by clicking the prompt icon, or in Claude Code by asking Claude to use them.

Resources

Pre-loaded data that Claude can reference without calling tools:

Usage Examples

Here are real prompts you can use:

"How much did I spend in February?"

"Show me my top 5 spending categories this month"

"Am I over budget on anything?"

"I spent 1,200 on electricity from my BHD account yesterday"

"What's my savings rate this month?"

"Show me all transactions from Cartera in the last 30 days"

"Transfer 5,000 from Checking to Savings"

"What are my spending trends for food over the last 6 months?"

"Create a category called Gym in Gastos Variables"

"Rename the Gym category to Fitness"

"Create a rule: when payee is Netflix, set category to Suscripciones"

"How have my finances been the last 3 months?"

How is this different?

Compared to other Actual Budget MCP servers:

Security

• This server connects to your Actual Budget instance using the credentials you provide

• Credentials are passed as environment variables and never stored by the MCP server

• All communication with your Actual Budget server happens locally (or to your self-hosted server)

• The server only accesses budget data through the official @actual-app/api library

• No data is sent to third parties

Troubleshooting

"Could not connect to Actual Budget server"

• Make sure Actual Budget is running (open the app or start the server)

• Check that ACTUAL_SERVER_URL is correct

• Run npx -y actual-budget-mcp --verify to test your connection

"Authentication failed"

• Your server requires a password. Set ACTUAL_PASSWORD in your config

• If you forgot the password, reset it in Actual Budget under Settings > Server

"Budget not found"

• Check your ACTUAL_BUDGET_ID. Find it in Settings > Show advanced settings > Sync ID

"Budget file is encrypted"

• Set ACTUAL_ENCRYPTION_PASSWORD with your encryption password

"Ambiguous name: matches X, Y"

• Be more specific. Instead of "BHD", try "BHD Nomina" or "BHD Mi Pais"

Node.js Requirement

"ReferenceError: navigator is not defined"

• @actual-app/api (including 26.6) references the navigator global, which is only available on Node.js 21+. On Node.js 20 or earlier it throws at import.

• Solution: Use Node.js 22 or higher.

Node Version Managers (fnm, nvm, volta)

MCP server shows "Server disconnected" in Claude Desktop

• Claude Desktop doesn't source your shell profile (.bashrc, .zshrc), so version managers like fnm, nvm, and volta won't work with the default npx command.

• Solution: Use the absolute path to node in your config. Find it with:

readlink -f $(which node)

Then update your claude_desktop_config.json:

{
  "mcpServers": {
    "actual-budget-mcp": {
      "command": "/home/user/.local/share/fnm/node-versions/v22.22.1/installation/bin/node",
      "args": ["/path/to/actual-budget-mcp/dist/index.js"],
      "env": {
        "ACTUAL_SERVER_URL": "http://localhost:5006",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_BUDGET_ID": "your-budget-sync-id"
      }
    }
  }
}

Alternatively, create a wrapper script mcp-wrapper.sh:

#!/bin/bash
export PATH="$HOME/.local/share/fnm/node-versions/v22.22.1/installation/bin:$PATH"
exec npx -y actual-budget-mcp "$@"

Then use it in your config:

{
  "mcpServers": {
    "actual-budget-mcp": {
      "command": "/path/to/mcp-wrapper.sh"
    }
  }
}

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

git clone https://github.com/henfrydls/actual-budget-mcp.git
cd actual-budget-mcp
npm install
npm run build
npm test               # Run unit tests
npm run test:connection # Needs .env configured

License

MIT - DLSLabs