# Actual Budget

> Actual Budget is an open-source MCP server for finance and payments. Connect Claude to your Actual Budget server for analysis, edits and previewed deletes. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, macOS, Windows, Linux
- **Website:** https://actual-mcp.henfrydls.com
- **Repository:** https://github.com/henfrydls/actual-budget-mcp
- **MCP Registry name:** io.github.henfrydls/actual-budget-mcp
- **Categories:** finance and payments
- **Listing updated:** 2026-11-14

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
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
```

### Claude Desktop (claude_desktop_config.json)

```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>"
      }
    }
  }
}
```

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

```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>"
      }
    }
  }
}
```

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

```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>"
      }
    }
  }
}
```

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

```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>"
      }
    }
  }
}
```

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

```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>"
      }
    }
  }
}
```

## Tools

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

## 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

- [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/actual-budget
