LabscoMCP early access ↗
agigante80MCP SERVER

Actual Budget MCP

Run your self-hosted Actual Budget from a chat — transactions, categories, rules, reports — across several budget files.

by agigante80 ↗Personal Finance & BudgetingCommunity

LABSCO SUMMARY

The query-engine tools are what keep a year of transactions from filling the context window.

Six of the tools run through Actual's native query engine and return aggregates — spend by category for a month, transactions above an amount — instead of handing the model thousands of rows to add up itself. That is the difference between asking where the money went and waiting while a chat client chokes. Multi-budget switching is handled properly on both transports: over HTTP the active budget is tied to the MCP session, and on stdio each process gets its own, so a switch does not leak between clients. Your data stays on your own Actual server throughout.

What it is

A TypeScript server with 74 tools over the Actual Budget API, running either as a local process for a desktop client or as a real remote server for a shared chat front end.

What you get

  • Accounts: actual_accounts_list, create, update, close, reopen, delete and actual_accounts_get_balance
  • Transactions: create, update, delete, batch update, import, plus actual_transactions_filter and actual_transactions_uncategorized for triage
  • Six tools built on Actual's own query engine — search by month, amount, category or payee, and actual_transactions_summary_by_category — returning aggregates rather than dumping raw rows into the context
  • Categories, category groups, payees with merge, tags and notes, each with full create, update and delete
  • Rules through actual_rules_create, update, delete and create_or_update, and schedules alongside them
  • Budget files: actual_budgets_list_available, actual_budgets_switch to change mid-conversation, transfer, import and export
  • actual_bank_sync, actual_query_run for a raw query, actual_entities_search and actual_server_info
  • actual_get_id_by_name, so you can name a category or payee instead of looking up its ID
  • OIDC with JWKS-validated tokens and per-user budget access lists, for a multi-user deployment

Requirements

A self-hosted Actual Budget instance and its details: ACTUAL_SERVER_URL, ACTUAL_PASSWORD and ACTUAL_BUDGET_SYNC_ID, with ACTUAL_BUDGET_PASSWORD if the file is encrypted. Node 22.0.0 or newer, from npm or the published Docker image; an Unraid Community Apps entry exists too. Local clients use stdio with no HTTP server or container needed; the HTTP transport is for remote, multi-user setups.

Setup effort

One command plus credentials — npx -y actual-mcp-server --stdio, then supply credentials

See installation options