# Actual Budget

Connects Actual Budget to an MCP client for budget analysis, transaction changes, and category management. Useful when you want to work with finances in chat.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 17
- Author: henfrydls
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/henfrydls/actual-budget-mcp
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/mcp/actual-budget

## What it does

This MCP server links Actual Budget with Claude Code and other MCP clients. It can answer questions about spending, produce projections, compare planned and actual amounts, and summarize a month. It also lets the model add or edit transactions and transfers, plus manage categories, payees, and rules.

Names can be used instead of IDs, with suggestions when a name is unclear. Delete operations show a preview and wait for confirmation, while `ACTUAL_READ_ONLY=1` removes write tools from the model. The server handles split and residual amounts across currencies and includes `repair_sync` for rebuilding local sync state. A running Actual Budget server is required; the Claude Code setup also needs Node.js 22.14 or newer.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `ACTUAL_SERVER_URL`, `ACTUAL_PASSWORD`, `ACTUAL_SESSION_TOKEN`, `ACTUAL_BUDGET_ID`, `ACTUAL_ENCRYPTION_PASSWORD`, `ACTUAL_READ_ONLY`, `ACTUAL_TOOLSET`, `ACTUAL_DATA_DIR`, `ACTUAL_HTTP_TIMEOUT_MS` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add actual-budget-mcp -e ACTUAL_SERVER_URL=<ACTUAL_SERVER_URL> -e ACTUAL_PASSWORD=<ACTUAL_PASSWORD> -e ACTUAL_SESSION_TOKEN=<ACTUAL_SESSION_TOKEN> -e ACTUAL_BUDGET_ID=<ACTUAL_BUDGET_ID> -e ACTUAL_ENCRYPTION_PASSWORD=<ACTUAL_ENCRYPTION_PASSWORD> -- npx -y actual-budget-mcp
```
Replace <…> with your own values. 4 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
codex mcp add actual-budget --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> -- npx -y actual-budget-mcp
```
Replace <…> with your own values. 4 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "actual-budget": {
            "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>"
            }
        }
    }
}
```
Replace <…> with your own values. 4 more environment variables are in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "actual-budget": {
            "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>"
            }
        }
    }
}
```
Replace <…> with your own values. 4 more environment variables are in the server README

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e ACTUAL_SERVER_URL=<ACTUAL_SERVER_URL> -e ACTUAL_PASSWORD=<ACTUAL_PASSWORD> -e ACTUAL_SESSION_TOKEN=<ACTUAL_SESSION_TOKEN> -e ACTUAL_BUDGET_ID=<ACTUAL_BUDGET_ID> -e ACTUAL_ENCRYPTION_PASSWORD=<ACTUAL_ENCRYPTION_PASSWORD> actual-budget npx -y actual-budget-mcp
```
Replace <…> with your own values. 4 more environment variables are in the server README

## When to use it
- find where money went during a month
- compare a budget with actual spending
- add an expense or transfer from chat
- change categories, payees, or rules
- rebuild the local sync state

## Example prompts
- Check how much I spent on food this month and compare it with the budget.
- Add this expense to Actual Budget, then check for a duplicate.
- List my budget categories and rules, and explain which ones apply to this transaction.

## Similar
- [Actual Budget MCP Server](https://affpapa.org/en/nevibecode/mcp/actual-budget-mcp-server.md) — MCP server · ★ 270
- [Expense Budget Tracker](https://affpapa.org/en/nevibecode/mcp/expense-budget-tracker.md) — MCP server · ★ 37
- [event-budget](https://affpapa.org/en/nevibecode/skills/event-budget.md) — skill · 5000 installs
- [budget-optimizer](https://affpapa.org/en/nevibecode/skills/onewave-ai-budget-optimizer.md) — skill · 429 installs
- [ads-budget](https://affpapa.org/en/nevibecode/skills/ads-budget.md) — skill · 4000 installs
- [zero-based-budget](https://affpapa.org/en/nevibecode/skills/zero-based-budget.md) — skill · 450 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md