Skip to content
MCP server

Actual Budget

Connect Claude to your Actual Budget server for analysis, edits and previewed deletes

Runs locallyStatus and history
Pricing
Open source
Platforms
CLI, self-hosted, macOS
Runs
Locally
Version
0.12.0
Listing updated
3 days ago

About Actual Budget

Actual Budget is an open-source MCP server for finance and payments. It runs locally on your machine and is started by your AI client.

This server connects an MCP client to your own Actual Budget instance, which can be local or remote. It offers 44 tools for reading accounts, budgets, transactions, categories, payees, rules and schedules, for analysis such as projections, category trends, budget vs actual and spending breakdowns, and for writes such as creating, splitting, transferring and recategorising transactions or moving budget amounts.

Care around changes is its theme. Every delete previews what it will remove and waits for confirmation, new transactions are checked for duplicates, and setting ACTUAL_READ_ONLY=1 hides all write tools from the model. A repair_sync tool rebuilds local sync state when the Actual API and your server disagree. Names can be used instead of IDs, dates like last month or hace 3 meses are understood in English and Spanish, and multi-currency splits are reconciled.

On Claude Desktop it installs as a drag-and-drop extension that needs no separate Node; other clients use npx with a server URL, password or session token, and the budget Sync ID. The README says data stays on your machine except for what goes to whichever model your client uses. A chat toolset of 18 everyday tools trims the tool descriptions, and an HTTP mode serves read and write paths with separate tokens. ChatGPT is not supported because its connectors need OAuth.

Install

Run in a terminal

claude mcp add actual-budget-mcp --env ACTUAL_SERVER_URL='<ACTUAL_SERVER_URL>' --env ACTUAL_PASSWORD='<ACTUAL_PASSWORD>' --env ACTUAL_SESSION_TOKEN='<ACTUAL_SESSION_TOKEN>' --env ACTUAL_BUDGET_ID='<ACTUAL_BUDGET_ID>' --env ACTUAL_ENCRYPTION_PASSWORD='<ACTUAL_ENCRYPTION_PASSWORD>' --env ACTUAL_ENCRYPTION_PASSWORDS='<ACTUAL_ENCRYPTION_PASSWORDS>' --env ACTUAL_HTTP_TOKEN='<ACTUAL_HTTP_TOKEN>' --env ACTUAL_HTTP_WRITE_TOKEN='<ACTUAL_HTTP_WRITE_TOKEN>' -- npx -y actual-budget-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "actual-budget-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "actual-budget-mcp"
      ],
      "env": {
        "ACTUAL_SERVER_URL": "<ACTUAL_SERVER_URL>",
        "ACTUAL_PASSWORD": "<ACTUAL_PASSWORD>",
        "ACTUAL_SESSION_TOKEN": "<ACTUAL_SESSION_TOKEN>",
        "ACTUAL_BUDGET_ID": "<ACTUAL_BUDGET_ID>",
        "ACTUAL_ENCRYPTION_PASSWORD": "<ACTUAL_ENCRYPTION_PASSWORD>",
        "ACTUAL_ENCRYPTION_PASSWORDS": "<ACTUAL_ENCRYPTION_PASSWORDS>",
        "ACTUAL_HTTP_TOKEN": "<ACTUAL_HTTP_TOKEN>",
        "ACTUAL_HTTP_WRITE_TOKEN": "<ACTUAL_HTTP_WRITE_TOKEN>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "actual-budget-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "actual-budget-mcp"
      ],
      "env": {
        "ACTUAL_SERVER_URL": "<ACTUAL_SERVER_URL>",
        "ACTUAL_PASSWORD": "<ACTUAL_PASSWORD>",
        "ACTUAL_SESSION_TOKEN": "<ACTUAL_SESSION_TOKEN>",
        "ACTUAL_BUDGET_ID": "<ACTUAL_BUDGET_ID>",
        "ACTUAL_ENCRYPTION_PASSWORD": "<ACTUAL_ENCRYPTION_PASSWORD>",
        "ACTUAL_ENCRYPTION_PASSWORDS": "<ACTUAL_ENCRYPTION_PASSWORDS>",
        "ACTUAL_HTTP_TOKEN": "<ACTUAL_HTTP_TOKEN>",
        "ACTUAL_HTTP_WRITE_TOKEN": "<ACTUAL_HTTP_WRITE_TOKEN>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "actual-budget-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "actual-budget-mcp"
      ],
      "env": {
        "ACTUAL_SERVER_URL": "<ACTUAL_SERVER_URL>",
        "ACTUAL_PASSWORD": "<ACTUAL_PASSWORD>",
        "ACTUAL_SESSION_TOKEN": "<ACTUAL_SESSION_TOKEN>",
        "ACTUAL_BUDGET_ID": "<ACTUAL_BUDGET_ID>",
        "ACTUAL_ENCRYPTION_PASSWORD": "<ACTUAL_ENCRYPTION_PASSWORD>",
        "ACTUAL_ENCRYPTION_PASSWORDS": "<ACTUAL_ENCRYPTION_PASSWORDS>",
        "ACTUAL_HTTP_TOKEN": "<ACTUAL_HTTP_TOKEN>",
        "ACTUAL_HTTP_WRITE_TOKEN": "<ACTUAL_HTTP_WRITE_TOKEN>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "actual-budget-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "actual-budget-mcp"
      ],
      "env": {
        "ACTUAL_SERVER_URL": "<ACTUAL_SERVER_URL>",
        "ACTUAL_PASSWORD": "<ACTUAL_PASSWORD>",
        "ACTUAL_SESSION_TOKEN": "<ACTUAL_SESSION_TOKEN>",
        "ACTUAL_BUDGET_ID": "<ACTUAL_BUDGET_ID>",
        "ACTUAL_ENCRYPTION_PASSWORD": "<ACTUAL_ENCRYPTION_PASSWORD>",
        "ACTUAL_ENCRYPTION_PASSWORDS": "<ACTUAL_ENCRYPTION_PASSWORDS>",
        "ACTUAL_HTTP_TOKEN": "<ACTUAL_HTTP_TOKEN>",
        "ACTUAL_HTTP_WRITE_TOKEN": "<ACTUAL_HTTP_WRITE_TOKEN>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "actual-budget-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "actual-budget-mcp"
      ],
      "env": {
        "ACTUAL_SERVER_URL": "<ACTUAL_SERVER_URL>",
        "ACTUAL_PASSWORD": "<ACTUAL_PASSWORD>",
        "ACTUAL_SESSION_TOKEN": "<ACTUAL_SESSION_TOKEN>",
        "ACTUAL_BUDGET_ID": "<ACTUAL_BUDGET_ID>",
        "ACTUAL_ENCRYPTION_PASSWORD": "<ACTUAL_ENCRYPTION_PASSWORD>",
        "ACTUAL_ENCRYPTION_PASSWORDS": "<ACTUAL_ENCRYPTION_PASSWORDS>",
        "ACTUAL_HTTP_TOKEN": "<ACTUAL_HTTP_TOKEN>",
        "ACTUAL_HTTP_WRITE_TOKEN": "<ACTUAL_HTTP_WRITE_TOKEN>"
      }
    }
  }
}

Configuration

  • ACTUAL_SERVER_URLURL of your Actual Budget server, for example http://localhost:5006Required
  • ACTUAL_PASSWORDPassword for your Actual Budget server. Not needed if you set ACTUAL_SESSION_TOKEN
  • ACTUAL_SESSION_TOKENSession token for servers behind OIDC, which have no password. Use instead of ACTUAL_PASSWORD; if both are set, the token wins
  • ACTUAL_BUDGET_IDYour budget's Sync ID, found under Settings > Show advanced settingsRequired
  • ACTUAL_ENCRYPTION_PASSWORDOnly needed if your budget file is end-to-end encrypted
  • ACTUAL_BUDGET_IDSEvery budget this server serves, comma separated, when it is more than one. Each tool then takes a budget_id, and each budget is opened in a process of its own
  • ACTUAL_ENCRYPTION_PASSWORDSA JSON object of budget sync id to encryption password, for when more than one of the budgets is encrypted. Each worker is given its own and never the map
  • ACTUAL_BUDGET_WORKERSHow many budgets stay open at once. Defaults to 3. A fourth budget closes the one that went longest without a call
  • ACTUAL_WORKER_IDLE_MINUTESHow long an open budget with nothing to do stays open. Defaults to 15
  • ACTUAL_WORKER_READY_SECONDSHow long a call waits for a budget that is still opening before it answers that it is still opening. Defaults to 45
  • ACTUAL_READ_ONLYSet to 1 to hide every write tool from the model, exposing only reads and analysis
  • ACTUAL_TOOLSETSet to chat to offer the 18 everyday tools instead of all 44, which is 17.4 KiB of tool descriptions instead of 39.7 KiB on every connection. Defaults to full
  • ACTUAL_DATA_DIRDirectory for the local budget cache
  • ACTUAL_HTTP_TIMEOUT_MSHow long to wait for your server to start replying, in milliseconds. Defaults to 60000; raise it if a GoCardless bank sync is being cut off
  • ACTUAL_HTTP_PORTServe MCP over HTTP on this port instead of stdio. Only for a server you run yourself and point clients at: a client that starts this package itself speaks stdio and cannot reach it once this is set
  • ACTUAL_HTTP_TOKENThe credential for the read path, /mcp. Required once ACTUAL_HTTP_PORT is set, and at least 32 characters
  • ACTUAL_HTTP_WRITE_TOKENA second credential, for the write path, /mcp-write. Without it the server serves no write path at all
  • ACTUAL_HTTP_HOSTWhat to bind to. Defaults to 127.0.0.1; inside a container that is unreachable, so 0.0.0.0 together with ACTUAL_HTTP_ALLOW_REMOTE
  • ACTUAL_HTTP_ALLOW_REMOTESet to 1 to bind somewhere other than loopback. Nothing here terminates TLS, so put something in front of it that does
  • ACTUAL_HTTP_ALLOWED_HOSTSHostnames to accept in the Host header, comma separated and without ports, for a server that is not on loopback. Anything else is answered 403
  • ACTUAL_SERVER_URLURL of your Actual Budget server. Inside the container localhost is the container, so use host.docker.internalRequired
  • ACTUAL_PASSWORDPassword for your Actual Budget server. Not needed if you set ACTUAL_SESSION_TOKEN
  • ACTUAL_SESSION_TOKENSession token for servers behind OIDC, which have no password. Use instead of ACTUAL_PASSWORD; if both are set, the token wins
  • ACTUAL_BUDGET_IDYour budget's Sync ID, found under Settings > Show advanced settingsRequired
  • ACTUAL_BUDGET_IDSEvery budget this server serves, comma separated, when it is more than one. Each tool then takes a budget_id, and each budget is opened in a process of its own
  • ACTUAL_ENCRYPTION_PASSWORDSA JSON object of budget sync id to encryption password, for when more than one of the budgets is encrypted. Each worker is given its own and never the map
  • ACTUAL_BUDGET_WORKERSHow many budgets stay open at once. Defaults to 3. A fourth budget closes the one that went longest without a call
  • ACTUAL_WORKER_IDLE_MINUTESHow long an open budget with nothing to do stays open. Defaults to 15
  • ACTUAL_WORKER_READY_SECONDSHow long a call waits for a budget that is still opening before it answers that it is still opening. Defaults to 45
  • ACTUAL_READ_ONLYSet to 1 to hide every write tool from the model, exposing only reads and analysis
  • ACTUAL_TOOLSETSet to chat to offer the 18 everyday tools instead of all 44, which is 17.4 KiB of tool descriptions instead of 39.7 KiB on every connection. Defaults to full
  • ACTUAL_HTTP_TIMEOUT_MSHow long to wait for your server to start replying, in milliseconds. Defaults to 60000; raise it if a GoCardless bank sync is being cut off
  • ACTUAL_HTTP_PORTServe MCP over HTTP on this port instead of stdio. Only for a server you run yourself and point clients at: a client that starts this package itself speaks stdio and cannot reach it once this is set
  • ACTUAL_HTTP_TOKENThe credential for the read path, /mcp. Required once ACTUAL_HTTP_PORT is set, and at least 32 characters
  • ACTUAL_HTTP_WRITE_TOKENA second credential, for the write path, /mcp-write. Without it the server serves no write path at all
  • ACTUAL_HTTP_HOSTWhat to bind to. Defaults to 127.0.0.1; inside a container that is unreachable, so 0.0.0.0 together with ACTUAL_HTTP_ALLOW_REMOTE
  • ACTUAL_HTTP_ALLOW_REMOTESet to 1 to bind somewhere other than loopback. Nothing here terminates TLS, so put something in front of it that does
  • ACTUAL_HTTP_ALLOWED_HOSTSHostnames to accept in the Host header, comma separated and without ports, for a server that is not on loopback. Anything else is answered 403

Tools this server provides (1)

Taken from the project documentation; the running server may differ.

repair_sync
Rebuilds the local sync state when the Actual API and your server disagree.

What it does

Budget analysis
Gives projections, category trends, budget vs actual and month summaries.
Delete previews
Shows what a delete will remove and waits for confirmation first.
Duplicate checks
Checks new transactions for duplicates before they are created.
Read-only mode
Hides every write tool from the model when ACTUAL_READ_ONLY is set to 1.
Sync repair
Rebuilds local sync state when the API and server disagree.
Multi-budget support
Serves several budgets, each opened in its own worker process.
Smaller toolset
A chat mode offers 18 everyday tools instead of all 44.

Good for

  • Ask where the money went this month and get a breakdown
  • Check whether spending is on track to stay within budget
  • Move budget amounts between categories in conversation
  • Add, split or transfer transactions without opening the app
  • Run a budget assistant with write tools disabled

Pricing

Open source

Free, MIT licensed; requires your own Actual Budget server

Prices change. Check actual-mcp.henfrydls.com before you buy.

Actual Budget FAQ

What do I need to run it?

An Actual Budget server, its URL and password or session token, and the budget Sync ID from Settings > Show advanced settings.

Can it make changes safely?

Deletes preview first and wait for confirmation, and ACTUAL_READ_ONLY=1 removes write tools entirely.

Does it work with ChatGPT?

Not currently. ChatGPT connectors use OAuth, while this server takes a fixed token over HTTP.

Does it work with local models?

Yes, with any MCP client, including one pointed at Ollama or LM Studio, which keeps budget data on your machine.

Which Node version is needed?

Node.js 22.14 or newer, except for the Claude Desktop extension, which uses the Node bundled with Claude Desktop.

Is Actual Budget free?

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

How do I add Actual Budget to Claude Code?

Run this command in your terminal: claude mcp add actual-budget-mcp --env ACTUAL_SERVER_URL='<ACTUAL_SERVER_URL>' --env ACTUAL_PASSWORD='<ACTUAL_PASSWORD>' --env ACTUAL_SESSION_TOKEN='<ACTUAL_SESSION_TOKEN>' --env ACTUAL_BUDGET_ID='<ACTUAL_BUDGET_ID>' --env ACTUAL_ENCRYPTION_PASSWORD='<ACTUAL_ENCRYPTION_PASSWORD>' --env ACTUAL_ENCRYPTION_PASSWORDS='<ACTUAL_ENCRYPTION_PASSWORDS>' --env ACTUAL_HTTP_TOKEN='<ACTUAL_HTTP_TOKEN>' --env ACTUAL_HTTP_WRITE_TOKEN='<ACTUAL_HTTP_WRITE_TOKEN>' -- npx -y actual-budget-mcp

What are the best alternatives to Actual Budget?

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

Alternatives to Actual Budget

  1. Remote MCP server exposing the Vybe Solana API to AI clients and code editors

    • 44 tools
    • Remote
    • 2.8K GitHub stars
    • Finance and payments
  2. Indian NSE and BSE stock market data for AI assistants through 48 MCP tools

    • 17 tools
    • Remote
    • Freemium
    • 150 GitHub stars
    • Finance and payments
  3. Budget Tracker

    MCP server

    Local MCP expense ledger that logs receipts and mileage, splits VAT and prepares rebilling

    • 14 tools
    • Remote
    • Freemium
    • 2 GitHub stars
    • Finance and payments
  4. Stock scores, what a price assumes, earnings quality and quiet profit revisions

    • 11 tools
    • Remote
    • Free
    • Finance and payments
  5. Provyan

    MCP server

    Backtested crypto signal results on 94 coins, with luck odds and sources

    • 4 tools
    • Remote
    • Free
    • Finance and payments
  6. TribuJus

    MCP server

    Read-only access to UK bank accounts, cards and transactions via TrueLayer Open Banking

    Not checked yet
    • 5 tools
    • Remote
    • Open source
    • Legal and government