# Actual Budget MCP Server

Actual Budget MCP Server is a Claude Code MCP server for accounts, transactions, budgets and reports. It asks for approval before changing data.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 80 repo stars
- Author: agigante80
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/agigante80/actual-mcp-server
- Updated: 2026-11-16
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/agigante80-actual-budget-mcp-server

## What it does

Actual Budget MCP Server connects an AI assistant to Actual Budget for expense searches, budget checks and account maintenance. It can inspect spending by payee, category or month, compare actual spending with the plan, and work with transactions, rules and categories.

The stdio setup needs Node.js 22 or later, an Actual Budget server URL, a password and a Sync ID. The HTTP option runs in Docker. The Actual Budget server and Sync ID are required for the connection; write operations wait for confirmation.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `ACTUAL_SERVER_URL`, `ACTUAL_PASSWORD`, `ACTUAL_BUDGET_SYNC_ID`, `ACTUAL_BUDGET_PASSWORD`, `MCP_BRIDGE_DATA_DIR`, `MCP_SSE_AUTHORIZATION` — 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 --env ACTUAL_SERVER_URL=<ACTUAL_SERVER_URL> --env ACTUAL_PASSWORD=<ACTUAL_PASSWORD> --env ACTUAL_BUDGET_SYNC_ID=<ACTUAL_BUDGET_SYNC_ID> --env ACTUAL_BUDGET_PASSWORD=<ACTUAL_BUDGET_PASSWORD> --env MCP_BRIDGE_DATA_DIR=<MCP_BRIDGE_DATA_DIR> --transport stdio agigante80-actual-budget-mcp-server -- npx -y actual-mcp-server
```
Replace <…> with your own values. 1 more environment variable is in the server README

### Codex

**Platform CLI**
```bash
codex mcp add agigante80-actual-budget-mcp-server --env ACTUAL_SERVER_URL=<ACTUAL_SERVER_URL> --env ACTUAL_PASSWORD=<ACTUAL_PASSWORD> --env ACTUAL_BUDGET_SYNC_ID=<ACTUAL_BUDGET_SYNC_ID> --env ACTUAL_BUDGET_PASSWORD=<ACTUAL_BUDGET_PASSWORD> --env MCP_BRIDGE_DATA_DIR=<MCP_BRIDGE_DATA_DIR> -- npx -y actual-mcp-server
```
Replace <…> with your own values. 1 more environment variable is in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "agigante80-actual-budget-mcp-server": {
            "command": "npx",
            "args": [
                "-y",
                "actual-mcp-server"
            ],
            "env": {
                "ACTUAL_SERVER_URL": "<ACTUAL_SERVER_URL>",
                "ACTUAL_PASSWORD": "<ACTUAL_PASSWORD>",
                "ACTUAL_BUDGET_SYNC_ID": "<ACTUAL_BUDGET_SYNC_ID>",
                "ACTUAL_BUDGET_PASSWORD": "<ACTUAL_BUDGET_PASSWORD>",
                "MCP_BRIDGE_DATA_DIR": "<MCP_BRIDGE_DATA_DIR>"
            }
        }
    }
}
```
Replace <…> with your own values. 1 more environment variable is in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "agigante80-actual-budget-mcp-server": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "actual-mcp-server"
            ],
            "env": {
                "ACTUAL_SERVER_URL": "<ACTUAL_SERVER_URL>",
                "ACTUAL_PASSWORD": "<ACTUAL_PASSWORD>",
                "ACTUAL_BUDGET_SYNC_ID": "<ACTUAL_BUDGET_SYNC_ID>",
                "ACTUAL_BUDGET_PASSWORD": "<ACTUAL_BUDGET_PASSWORD>",
                "MCP_BRIDGE_DATA_DIR": "<MCP_BRIDGE_DATA_DIR>"
            }
        }
    }
}
```
Replace <…> with your own values. 1 more environment variable is 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_BUDGET_SYNC_ID=<ACTUAL_BUDGET_SYNC_ID> -e ACTUAL_BUDGET_PASSWORD=<ACTUAL_BUDGET_PASSWORD> -e MCP_BRIDGE_DATA_DIR=<MCP_BRIDGE_DATA_DIR> agigante80-actual-budget-mcp-server npx -y actual-mcp-server
```
Replace <…> with your own values. 1 more environment variable is in the server README

## When to use it
- find spending by payee, category or month
- compare this month’s spending with the budget plan
- add or correct transactions after approval
- assign categories to uncategorised transactions
- move money between budget categories

## Example prompts
- Show how much I spent on groceries last month, grouped by payee.
- Which payees cost me the most this year?
- Find uncategorised transactions that look like my usual grocery purchases and categorise them after I approve.

## Similar
- [Actual Budget](https://affpapa.org/en/nevibecode/mcp/actual-budget.md) — MCP server · ★ 20 repo stars
- [Expense Budget Tracker](https://affpapa.org/en/nevibecode/mcp/expense-budget-tracker.md) — MCP server · ★ 43 repo stars
- [NYC Budget](https://affpapa.org/en/nevibecode/mcp/nyc-budget.md) — MCP server · ★ 20 repo stars
- [event-budget](https://affpapa.org/en/nevibecode/skills/event-budget.md) — skill · 6800 installs
- [budget-optimizer](https://affpapa.org/en/nevibecode/skills/onewave-ai-budget-optimizer.md) — skill · 454 installs
- [budget-planner](https://affpapa.org/en/nevibecode/skills/budget-planner.md) — skill · ★ 12746 repo stars

## Other versions with the same name
- [Actual Budget MCP Server · s-stefanov](https://affpapa.org/en/nevibecode/mcp/actual-budget-mcp-server.md) — ★ 293 repo stars

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