actualbudget-mcp-server

MCP server for Actual Budget, built for Claude, Cursor, and other AI agents.

Actual has no REST API. Its official @actual-app/api package is the app's own engine running headless: it downloads the whole budget into a local SQLite file, runs every method against that copy, and syncs CRDT messages back to the server. That architecture is why generic per-request wrappers fight it — and why this server is built around a long-lived engine singleton instead:

• Init once, never per call. The budget downloads at startup; tool calls are then local reads/writes with no init/teardown races.
• Serialized writes. All mutations run through a mutex, so bulk operations can't corrupt or lock the budget file.
• Graceful shutdown. SIGINT/SIGTERM/stdin-close flush pending sync and release the SQLite file.
• Cache-reset recovery. actual_reload_budget deletes the stale local cache and re-downloads — no more restarting the MCP server by hand after resetting the budget cache in the Actual UI.
• Full budget-envelope surface. Set budgeted amounts, carryover, and holds; move accounts on/off budget; create income categories — operations the API supports but existing MCP wrappers don't expose.
• Mutation safety. Every write is saved as a {before, request, after} JSON backup in the temp directory, write tools are opt-in via ACTUAL_ENABLE_WRITE=true, and destructive tools carry MCP destructiveHint annotations.
• Defensive name handling. Some MCP clients HTML-escape arguments (& → &); names are unescaped before they reach Actual.

Setup

npm install
npm run build

Configure via environment (see .env.example):

Variable	Required	Purpose
ACTUAL_SERVER_URL	yes	Your actual-server instance URL
ACTUAL_PASSWORD	yes	Server login password
ACTUAL_BUDGET_SYNC_ID	yes	Settings → Show advanced settings → Sync ID
ACTUAL_DATA_DIR	yes	Local cache directory for the budget file
ACTUAL_BUDGET_ENCRYPTION_PASSWORD	no	Only for end-to-end encrypted files
ACTUAL_ENABLE_WRITE	no	Write tools registered only when exactly true

Claude Code / Cursor MCP config:

{
  "mcpServers": {
    "actual-budget": {
      "command": "node",
      "args": ["/path/to/actualbudget-mcp-server/dist/index.js"],
      "env": {
        "ACTUAL_SERVER_URL": "https://actual.example.com",
        "ACTUAL_PASSWORD": "...",
        "ACTUAL_BUDGET_SYNC_ID": "...",
        "ACTUAL_DATA_DIR": "/path/to/cache",
        "ACTUAL_ENABLE_WRITE": "true"
      }
    }
  }
}

Tools (53)

Always on (read/admin):

• actual_get_accounts, actual_get_categories, actual_get_budget_months, actual_get_budget_month
• actual_get_transactions, actual_search_transactions (cross-account, filters: payee substring / amount / category / account / date range / uncategorized-only)
• actual_get_payees, actual_get_common_payees, actual_get_payee_rules, actual_get_rules, actual_get_tags, actual_get_schedules, actual_get_note
• actual_query — general read-only AQL access to any table with filters, joins, groupBy, and aggregates (spending-by-category reports in one call)
• actual_get_server_version, actual_sync_now, actual_reload_budget, actual_prune_stale (dry-run by default)

With ACTUAL_ENABLE_WRITE=true:

• Accounts: actual_create_account, actual_update_account (incl. on/off budget), actual_close_account (transfer-aware), actual_reopen_account, actual_delete_account
• Categories: actual_create_category (incl. is_income), actual_update_category, actual_delete_category, actual_create_category_group (create-then-update workaround for the engine dropping is_income on create), actual_update_category_group, actual_delete_category_group
• Budget envelope: actual_set_budget_amount, actual_set_budget_amounts (batch, via batchBudgetUpdates), actual_set_budget_carryover, actual_hold_budget_for_next_month, actual_reset_budget_hold
• Transactions: actual_add_transaction, actual_update_transaction (recategorize, payee, notes, date, amount, cleared), actual_delete_transaction, actual_import_transactions (batch with imported_id dedup and dry-run preview)
• Payees: actual_create_payee, actual_update_payee, actual_merge_payees, actual_delete_payee
• Rules: actual_create_rule, actual_update_rule, actual_delete_rule
• Schedules: actual_create_schedule, actual_update_schedule, actual_delete_schedule
• Tags: actual_create_tag, actual_update_tag, actual_delete_tag
• Notes: actual_update_note
• Bank sync: actual_run_bank_sync (one account or all)

Amounts in tool inputs are major currency units (123.45); Actual stores minor units (cents) and conversion happens at the boundary. Transaction lists return raw minor-unit integers; account balance and balance_current are converted to major units (balance_current: null means the account has never bank-synced). totalBudgeted in actual_get_budget_month is normalized to agree in sign with its per-group siblings (the engine reports it negated internally).

Transaction update/delete compensate for an upstream engine quirk: the engine's handlers return before their internal batch write is applied, so this server polls until the change is visible before responding — responses and backups always reflect applied state. The same one-operation lag can make a balance read immediately after actual_close_account (with transfer) show the pre-transfer value; the closed state itself is immediate.

Known limitations

• Transaction splits (subtransactions) are not exposed; use the Actual UI
• Single-budget by design: loadBudget/runImport/getBudgets multi-file management is intentionally out of scope (one server instance per budget file)
• actual_run_bank_sync is registered but exercised only against the engine, not against live GoCardless/SimpleFIN providers
• Streamable HTTP transport not yet implemented (stdio only)

License

Dual-licensed: AGPL-3.0-only for open-source use, with a commercial license available. Contact hello@nightsquawk.tech.