# Actual Budget [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/henfrydls/actual-budget-mcp.git  
**GitHub Stars:** 17  
**npm Downloads (last month):** 2439  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/actual-budget

## Description
Spending analysis and safe writes for Actual Budget: every delete previews and asks first.

## Tools
Capabilities this server exposes over MCP:

- **list_accounts** — All accounts with balances
- **get_budget_month** — Budget for a specific month
- **get_transactions** — Transactions with filters
- **get_category_balance** — Category history across a window of months
- **get_budget_summary** — Executive budget overview
- **get_categories** — All category groups and categories, with `include_hidden` for the hidden ones
- **get_payees** — All payees in the budget
- **get_schedules** — Recurring payments: what is due next, how much, and whether the last one posted
- **reconcile_account** — Compare an account against a bank figure and explain the gap
- **get_rules** — All transaction rules
- **balance_history** — Account balance over time
- **budget_vs_actual** — Budgeted vs spent per category
- **spending_projection** — End-of-month spending forecast
- **category_trends** — Spending trends over a window of months
- **spending_by_category** — Spending breakdown by category
- **monthly_summary** — Income vs expenses vs savings
- **create_transaction** — Add a new transaction
- **create_transactions** — Add several at once, all or nothing
- **create_split_transaction** — One charge across several categories
- **update_transaction** — Edit an existing transaction
- **delete_transaction** — Remove a transaction (previews first, see [Safety](#safety))
- **update_budget_amount** — Set a budget amount, or add to it
- **transfer_between_categories** — Move budgeted money between categories, creating no transaction
- **hold_for_next_month** — Keep part of a month's unassigned money for the next month
- **set_category_carryover** — Carry a category's overspending forward instead of taking it off the top
- **recategorize_transaction** — Move to another category
- **create_transfer** — Transfer between accounts
- **reconcile_currency_residual** — Clear accumulated FX-rate residual
- **run_bank_sync** — Sync with linked banks
- **create_category** — Create a new category
- **update_category** — Rename or hide a category
- **delete_category** — Delete a category (previews first, see [Safety](#safety))
- **create_category_group** — Create a new group
- **update_category_group** — Rename or hide a group
- **delete_category_group** — Delete a group (previews first, see [Safety](#safety))
- **create_payee** — Create a new payee
- **update_payee** — Rename a payee
- **delete_payee** — Delete a payee (previews first, see [Safety](#safety))
- **create_rule** — Create a transaction rule
- **delete_rule** — Delete a rule (previews first, see [Safety](#safety))
- **create_account** — Create an on- or off-budget account
- **delete_account** — Delete an account and its history
- **update_account** — Rename an account
- **repair_sync** — Repair an out-of-sync budget

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "actual-budget": {
    "command": "npx",
    "args": ["-y","actual-budget-mcp"],
    "env": {
      "ACTUAL_SERVER_URL": "",
      "ACTUAL_PASSWORD": "",
      "ACTUAL_BUDGET_ID": ""
    }
  }
}
```

**Requires environment variables:** `ACTUAL_SERVER_URL`, `ACTUAL_PASSWORD`, `ACTUAL_BUDGET_ID` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What Actual Budget does

Actual Budget MCP server exposes an Actual Budget budget to an MCP client, allowing an AI model to inspect finances and perform selected changes. Read operations cover accounts, balances, budgets, transactions, categories, payees, schedules, rules, and account history. Analysis tools calculate budget-versus-actual results, category trends, spending breakdowns, monthly summaries, and end-of-month projections.

Write operations cover transactions, splits, transfers, budget allocations, category carryover, recategorization, categories, bank synchronization, and reconciliation tasks. The server accepts names such as account or category names instead of requiring users to provide internal IDs, and it can interpret natural-language dates in English and Spanish.

## How it works

The server connects to a local or remote Actual Budget server using the Actual Budget server URL, password, and budget Sync ID. MCP clients send tool calls to the local server process, which reads from or updates the selected budget. Output is formatted as tables and summaries rather than raw JSON.

Delete operations show a preview and wait for confirmation before removing data. Setting `ACTUAL_READ_ONLY=1` prevents write tools from being exposed to the model. Multi-currency workflows include split handling and reconciliation of accumulated exchange-rate residuals. A recovery path can rebuild local synchronization state when the Actual API and server become out of sync.

## Setup and configuration

Actual Budget must already be running locally or remotely. The standard installation paths require Node.js 22.14 or newer. The Claude Desktop extension is an exception: it includes its runtime dependencies and does not require a separate Node.js installation.

For a command-line setup, install or run the npm package with `npx` and provide these environment variables:

- `ACTUAL_SERVER_URL`: URL of the Actual Budget server
- `ACTUAL_PASSWORD`: Actual Budget password
- `ACTUAL_BUDGET_ID`: budget Sync ID

Claude Code and Claude Desktop can use an `npx` MCP configuration. Cursor and VS Code provide MCP installation or configuration flows. Claude Desktop also supports a packaged `.mcpb` extension whose settings UI accepts the server URL, password, and Sync ID; it stores the password and session token in the operating system keychain.

## Tools and capabilities

Available operations include:

- Inspect accounts, balances, budgets, categories, payees, schedules, rules, and transactions.
- Compare accounts with bank figures and review balance history.
- Analyze spending by category, category trends, budget-versus-actual results, monthly income and expenses, and projected month-end spending.
- Create single, bulk, split, and transfer transactions; edit, delete, or recategorize transactions.
- Set or add budget amounts, move funds between categories, hold unassigned money for the next month, and configure category carryover.
- Create categories, synchronize linked banks, and reconcile currency residuals.

## Limitations and notes

ChatGPT connectors cannot directly start this local stdio server; they require a remote MCP endpoint using HTTPS with SSE or Streamable HTTP. Clients that can run local MCP processes are supported instead, including Claude Desktop, Claude Code, Cursor, VS Code, Gemini CLI, Codex, and local-model setups using Ollama or LM Studio.

Financial data is sent to whichever model the MCP client uses. Running a local model can keep that model interaction on the local machine, depending on the client configuration. Review delete previews and consider read-only mode when granting an agent access to a live budget.

_Full upstream README: https://allmcps.com/mcp/actual-budget/readme_