MCP Actual

An MCP server for Actual Budget. It connects to your Actual sync server, opens one budget file, and exposes it to MCP clients over streamable HTTP (/mcp) or stdio.

Tools

Read-only tools are always served. Tools marked ✏️ modify the budget and are served only when ACTUAL_ENABLE_WRITES is on (the default) — when it is off they are not advertised at all.

Accounts & context

Transactions

Payees

Rules

Budgets

There are no delete tools — see TODO_IDEAS.md. All amounts are integer cents (amount), with a decimal sibling (amountDecimal) for display; tools accept integers only.

Example list_accounts result:

{
  "accounts": [
    {
      "id": "729cb...",
      "name": "Checking",
      "amount": 123456,
      "amountDecimal": 1234.56,
      "offBudget": false,
      "closed": false
    }
  ],
  "onBudgetTotal": 123456,
  "total": 123456
}

Totals cover open (non-closed) accounts; onBudgetTotal excludes off-budget tracking accounts. The budget is synced with the server before every read.

Related MCP server: actual-mcp

Prompts

The server exposes MCP prompts, so a client can pull a vetted workflow instead of you writing one. Start with explore_budget.

Every argument is optional — the prompt asks rather than guessing — and the prompts are available whether or not writes are enabled. With ACTUAL_ENABLE_WRITES off they render a read-only variant that stops after the analysis instead of vanishing, so the agent is told writing is unavailable rather than left to improvise.

Prefer these over driving the sharp tools yourself: apply_rule_actions applies actions unconditionally and merge_payees cannot be undone, and the prompts are what enforce previewing and confirming first.

What you need before you start

You need three things, and nothing else. There is no API key and no username — an Actual sync server authenticates with a single password, and the budget is selected by its Sync ID.

1. A running Actual sync server and its URL, e.g. https://budget.example.com or http://192.168.1.50:5006 — the same URL you open the Actual web UI at.

2. The server password — what you type on the Actual login screen.

3. The budget's Sync ID — open Actual → Settings → Advanced settings → "Sync ID". It is a UUID like a1b2c3d4-….. This is not the budget's display name and not the My-Finances-xxxx folder name.

Plus Node.js ≥ 22.18, or Docker.

Configuration

All configuration is environment variables — copy .env.example to .env and fill in the three required values. docker compose reads that same .env.

Missing or malformed values are reported at startup with every offending variable named at once.

Pointing at an Actual server that also runs in Docker: use its service name (http://actual_server:5006) and put both on the same Docker network. Inside this container, localhost is this container, not your host.

Running

Local

npm install
cp .env.example .env   # fill in your server URL, password, and sync id
npm run build
npm start              # HTTP server on :3000, MCP at /mcp

Docker

cp .env.example .env    # fill in ACTUAL_SERVER_URL, ACTUAL_PASSWORD, ACTUAL_SYNC_ID
docker compose up -d
docker compose logs -f  # confirm it opened the budget

Compose refuses to start with a message naming any required variable you left unset. ./data is mounted at /data so the downloaded budget survives restarts.

Without compose, the same three variables must be passed explicitly:

docker run -d --name mcp-actual -p 3000:3000 \
  -v "$PWD/data:/data" \
  -e ACTUAL_SERVER_URL=https://budget.example.com \
  -e ACTUAL_PASSWORD='your-actual-password' \
  -e ACTUAL_SYNC_ID=00000000-0000-0000-0000-000000000000 \
  -e MCP_ACTUAL_TOKEN="$(openssl rand -hex 32)" \
  mcp-actual

Published images: ghcr.io/<owner>/mcp-actual and Docker Hub <dockerhub-user>/mcp-actual, tagged latest and by semver.

Connecting a client

Streamable HTTP — point the client at http://<host>:3000/mcp, sending Authorization: Bearer $MCP_ACTUAL_TOKEN if a token is configured.

stdio — for local clients such as Claude Code:

{
  "mcpServers": {
    "actual": {
      "command": "node",
      "args": ["/path/to/mcp-actual/dist/stdio.js"],
      "env": {
        "ACTUAL_SERVER_URL": "https://budget.example.com",
        "ACTUAL_PASSWORD": "…",
        "ACTUAL_SYNC_ID": "…",
        "DATA_DIR": "/path/to/mcp-actual/data"
      }
    }
  }
}

Or, after npm link, use the mcp-actual-stdio binary.

GET /api/status is an unauthenticated liveness probe (name, version, and the configured Actual server URL) used by the Docker healthcheck.

Security notes

• The server holds your Actual password and reads your full financial data. It refuses to start without MCP_ACTUAL_TOKEN, unless you set SECURE_LOCAL_NET=true to say an unauthenticated server is what you intended. An unset variable looks exactly like a misspelled one, so the old behaviour — start anyway and warn — turned a single typo into an open server.

• Writes are on by default. An agent connected to this server can change categories, rename and merge payees, create rules, and move budgeted money. Combined with SECURE_LOCAL_NET=true, anyone who can reach the port can do the same — the server warns loudly at startup when it detects that combination. Set ACTUAL_ENABLE_WRITES=false for a read-only deployment.

• merge_payees cannot be undone. There are no delete tools at all.

• DATA_DIR contains a plaintext SQLite copy of the budget. Treat it as sensitive; do not commit it (data/ is gitignored).

Development

npm run dev     # watch mode, .ts run directly by Node
npm run check   # biome + tsc
npm test        # vitest

See AGENTS.md for architecture and conventions.