actual-mcp

An MCP server for Actual Budget — with a per-tool safety layer.

Actual has no HTTP or MCP surface of its own; it ships a Node SDK. This wraps that SDK as an MCP server so any agent — Claude Desktop, Cursor, your own — can read and edit your budget in natural language.

The difference from a plain wrapper: every tool carries its own risk. A read is a read. A mutation says so. And a delete can never fire on the agent's say-so — it returns a confirmation token and refuses until you call it again with confirm: true. The model can plan freely; it cannot quietly wipe a category because a prompt drifted.

Giving an agent write access to your finances is a liability unless the tools themselves carry the seatbelt. The safest place to enforce a rule is the tool, not the prompt.

Requirements

• Node.js 20+

• A running, self-hosted Actual sync server (the actual-server you sync your budget to — not the desktop app). You need its URL, its password (if set), and the Sync ID of the budget you want to expose.

Related MCP server: YNAB MCP Server

Quick start

1. Find your Sync ID

In Actual: Settings → Show advanced settings → Sync ID. It's a UUID like a1b2c3d4-....

2. Add the server to your MCP client

Edit claude_desktop_config.json (Claude → Settings → Developer → Edit Config):

{
  "mcpServers": {
    "actual": {
      "command": "npx",
      "args": ["-y", "actual-mcp"],
      "env": {
        "ACTUAL_SERVER_URL": "https://actual.example.com",
        "ACTUAL_PASSWORD": "your-server-password",
        "ACTUAL_SYNC_ID": "your-sync-id"
      }
    }
  }
}

Restart Claude Desktop. You'll see the tools appear under the 🔌 icon.

Any stdio MCP client works — point it at npx -y actual-mcp with the same four env vars. In Cursor: Settings → MCP → Add new and use the same command/args/env shape.

3. Ask it things

What did I spend on groceries last month?
List my accounts and their balances.
Move R$200 from Dining to Savings for July.
Add a R$54.90 transaction to Nubank, payee "Uber", category Transport, dated today.

Configuration

Amounts are integer minor units, matching the Actual SDK — R$200.00 is 20000, and outflows are negative (-5490 = R$54.90 spent).

The safety model

Every tool's level is exposed three ways so the seatbelt is visible before a call: in the tool description, in MCP readOnlyHint / destructiveHint annotations, and — for guarded tools — as a hard refusal at call time.

What a guarded call looks like. The agent tries to delete, and gets back a refusal with the exact arguments and a confirmation token:

// → delete_category { "id": "cat-abc-123" }
// ← (isError)
⚠️ "delete_category" is a destructive action and needs confirmation.
It will run with:
{ "id": "cat-abc-123" }
To proceed, call "delete_category" again with "confirm": true.
Confirmation token: 75aa4f772b62

Only an explicit re-invocation clears it:

// → delete_category { "id": "cat-abc-123", "confirm": true }
// ← { "ok": true }

The human reading the transcript sees precisely what "yes" authorized.

Tools (28)

Troubleshooting

• "actual-mcp is not configured" — ACTUAL_SERVER_URL or ACTUAL_SYNC_ID is missing from the client's env block.

• Can't connect / auth fails — check the URL is the sync server (not the desktop app) and the password matches. Test it by logging into that URL in a browser.

• Wrong or empty data — the Sync ID points at a different budget file. Re-copy it from Settings → Show advanced settings → Sync ID.

• Tools don't appear in Claude Desktop — fully quit and reopen; check the config file is valid JSON.

Verify your setup

Before wiring it into an agent, confirm the server can reach your Actual instance. This prints only counts — never names or amounts:

ACTUAL_SERVER_URL=https://actual.example.com \
ACTUAL_SYNC_ID=your-sync-id \
ACTUAL_PASSWORD=your-password \
npm run smoke

✓ connected to Actual
  accounts:        1
  categories:      63
  category groups: 17
  budget months:   21
✓ clean shutdown

Develop

npm install
npm run build
npm run inspect          # @modelcontextprotocol/inspector against the built server
npm run smoke            # connection check (counts only)

License

MIT © Mauricio Juba · TYPE:ZERO

Not affiliated with Actual Budget. Built on the official @actual-app/api.