English | Español

Actual Budget MCP Server

An MCP (Model Context Protocol) server that connects LLMs — Claude Desktop and any MCP-capable client — to a self-hosted Actual Budget instance. It is purpose-built for LLM consumption: correct financial semantics (transfers excluded from spending summaries, net worth including off-budget accounts), amounts converted server-side so the model never does cents math, compact outputs, fresh data via sync-with-TTL, and real split transactions backed by subtransactions.

Feature highlights

The design rests on five pillars:

• Correct financial semantics — transfers (transfer_id) are excluded from spending summaries so amounts are never double-counted, and net worth includes off-budget accounts (pensions, funds, mortgage).
• Server-side unit conversion — Actual stores amounts in cents; every tool returns values already divided by 100, with an amount_formatted field. The LLM never does the math.
• Compact, LLM-friendly outputs — responses are trimmed to what a model needs to answer, keeping token usage low.
• Fresh data with sync-with-TTL — the server syncs with Actual before serving, caching the sync for a short TTL to stay fast without going stale.
• Real split transactions — split_transaction creates genuine subtransactions in Actual, not fake notes or workarounds.

Install in Claude Desktop (recommended)

Requirements: a Mac with Apple Silicon (M1 or later), Claude Desktop, and a self-hosted Actual Budget server you can reach. On Intel Macs, Windows or Linux, use Manual installation instead.

1. Download the latest actual-budget-mcp-es.mcpb from the Releases page.
2. Find your Sync ID — open Actual Budget in the browser, go to Settings → Advanced Settings → IDs, and copy the Sync ID.
3. Install — in Claude Desktop, open Settings → Extensions, drag the downloaded .mcpb file onto the page, review what it declares, and select Install. Claude Desktop will note the extension is not signed — that's expected for a self-distributed bundle.
4. Fill the form Claude Desktop shows:
   • Actual server URL — e.g. https://actual.example.org/
   • Server password — the one you use to open Actual in the browser (stored by Claude Desktop's secure storage, not in a config file)
   • Budget Sync ID — from step 2
   • Locale and Currency — e.g. es-ES and EUR; defaults are en-US and USD
   • Enable write tools — leave this off for now (see below)
   • Message language — es or en; defaults to es
5. Check it works — start a new conversation and ask "what accounts do I have?". You should get your account list with balances.

Turning on write access

With the checkbox off you get the 8 read-only tools. Turn it on (Settings → Extensions → this extension → configure) to add the 8 write tools: editing and categorizing transactions, real splits, scheduled transactions, budget assignment and category notes. Claude Desktop asks for your approval before each call unless you grant it standing permission, and there are no delete tools.

Updating

Download the newer .mcpb and drag it in again — your configuration is kept.

If every tool fails after a Claude Desktop update

The bundle ships a native SQLite module (better-sqlite3) compiled for one specific Node ABI. Claude Desktop does not run extensions with the system's Node: it starts them inside its own Electron runtime, so the module has to match that runtime. When a Claude Desktop update changes it, the module can no longer be loaded and the extension cannot work.

The server detects this at startup and says so plainly: every tool answers with the two version numbers involved and tells you to install a newer bundle, instead of failing with a confusing message about the budget being closed.

Nothing on your side fixes this — the bundle has to be rebuilt for the new runtime. Get a newer release, or build one yourself with npm run bundle on a machine that has the updated Claude Desktop installed.

This affects the .mcpb bundle only. A manual installation runs under your own Node and is immune to it.

Manual installation

For other MCP clients, Intel Macs, Windows and Linux. Requires Node.js >= 22 and a self-hosted Actual Budget server (>= 25.x; built against API 26.7) reachable over the network.

The project is written in TypeScript, so build it before use:

git clone https://github.com/marcoaperez/actual-budget-mcp-es.git
cd actual-budget-mcp-es
npm install
npm run build          # compiles TypeScript to dist/

This produces dist/index.js, the entry point your MCP client runs.

Need your Sync ID? See step 2 of Install in Claude Desktop above.

Client configuration

Add this to your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json), or the equivalent configuration file for your MCP client. Point command at node and args at the compiled dist/index.js using an absolute path:

{
  "mcpServers": {
    "actual-budget": {
      "command": "node",
      "args": ["/absolute/path/to/actual-budget-mcp-es/dist/index.js"],
      "env": {
        "ACTUAL_SERVER_URL": "https://actual.example.org/",
        "ACTUAL_SERVER_PASSWORD": "your-password",
        "ACTUAL_SYNC_ID": "00000000-0000-0000-0000-000000000000",
        "LOCALE": "es-ES",
        "CURRENCY": "EUR",
        "ENABLE_WRITE": "false"
      }
    }
  }
}

Use "LOCALE": "en-US" and "CURRENCY": "USD" for US formatting, or "es-ES" / "EUR" for Spain. Set "ENABLE_WRITE": "true" only when you want the write tools (see below). Restart Claude Desktop after saving so it detects the new MCP server.

During development you can skip the build and run TypeScript directly with tsx: "command": "npx", "args": ["tsx", "/absolute/path/to/actual-budget-mcp-es/src/index.ts"].

Environment variables

The first three variables are required; the rest have defaults.

Variable	Required	Default	Description
ACTUAL_SERVER_URL	Yes	—	URL of the self-hosted Actual server
ACTUAL_SERVER_PASSWORD	Yes	—	Actual server password
ACTUAL_SYNC_ID	Yes	—	Budget Sync ID (Settings → Advanced → Sync ID)
ACTUAL_DATA_DIR	No	./data	Folder where the local copy of the budget is downloaded
LOCALE	No	en-US	Locale for formatting amounts and dates (e.g. es-ES)
CURRENCY	No	USD	3-letter ISO currency code (e.g. EUR)
SYNC_TTL_SECONDS	No	60	Seconds the sync is cached before re-syncing
ENABLE_WRITE	No	false	Enables the 8 write tools (categorize, splits, schedules, budget, notes)
MESSAGES_LANG	No	es	Language of the server's error messages: es or en

Tools

Read tools (8)

Always available.

Tool	Description
get_accounts	Accounts with current balance; includes off-budget accounts (pensions, funds, mortgage) by default
get_net_worth	Full net worth: on-budget + off-budget with a per-account breakdown
get_categories	Category groups and categories with their IDs (needed by the write tools)
get_transactions	Transactions by date range with optional filters (account, category, text, amount, uncategorized). Excludes transfers. Paginated (max 200)
get_spending_summary	Spending aggregated by category, payee or month. Always excludes transfers
get_budget_month	A month's budget state: to-budget, income, totals and budgeted/spent/balance per category
get_budget_averages	Mean, median and max spending per category over the last N full months — input for preparing the budget
get_schedules	Scheduled/recurring transactions configured in Actual (name, next date, amount)

Write tools (8)

Registered only when ENABLE_WRITE=true.

Tool	Description
update_transaction	Fix a transaction (amount, category, payee, notes, date)
categorize_transactions	Categorize in bulk (max 50), with a per-item result
split_transaction	Split a transaction into real parts — replaces the transaction (new id)
create_transaction	Record an expense/income, with optional splits at creation
create_schedule	Create a scheduled/recurring transaction
set_budget	Assign budget in bulk to several categories of a month
transfer_budget	Move assigned budget between categories
update_category_note	Category notes and goal templates

Notes on the write tools

• They only appear when ENABLE_WRITE=true is set in the env block (restart the client after changing it).
• Input amounts are in currency units (euros/dollars, not cents); the server handles the conversion.
• split_transaction replaces the original transaction with a new one carrying subtransactions, so the resulting transaction has a new id.

Safety

• No delete tools — the server cannot remove transactions, accounts or budgets.
• Write disabled by default — write tools are never registered unless ENABLE_WRITE=true.
• Split guards — the write tools guard against editing split parts or split parents directly.
• Never commit your .env. The Actual password lives only in your local .env or the client config.

Three things worth knowing before you enable writes:

• data/ holds a plain, unencrypted copy of your whole budget (created owner-only, mode 0700).
• Payee names and notes come from bank sync or CSV imports: they are untrusted text, not instructions. Keep per-call approval on in your MCP client.
• split_transaction replaces the transaction, so it gets a new id.
• Every MCP client you connect starts its own server process. Only one process can open a budget at a time, so extra instances automatically use their own local copy (<data dir>-instance-<pid>). In a manual installation you can set ACTUAL_DATA_DIR per client if you prefer to control it (the Claude Desktop bundle does not expose this setting).

The full security model — trust boundary, credentials, destructive operations, input validation and how to report a vulnerability — is documented in SECURITY.md.

Privacy Policy

This software collects nothing: no telemetry, no analytics, no update checks. It runs on your machine and talks only to your own Actual Budget server and to the MCP client you connect it to — which sees the financial data you ask about, under its own privacy policy. The local copy of your budget is unencrypted and lives only on your machine.

Full text: PRIVACY.md · en español

Development

npm test        # full suite with Vitest (127 tests)
npm run dev     # runs src/index.ts with tsx (no build)
npm run smoke   # manual check against the real Actual server (requires .env; not part of CI)

The server talks over stdio (stdin/stdout), so running it manually shows no interactive output — logs go to stderr.

Adding a new tool

1. Create a file in src/tools/my_new_tool.ts
2. Export a ToolDef (name, description, readOnly, inputSchema with Zod, handler)
3. Import and register it in the allTools array of src/tools/index.ts

The handler(input, ctx) receives an initialized { api, config } context; use moneyFields/toUnits from src/core/money.js to always return amounts in units (never cents).

Releasing a bundle

The bundle is tied to Claude Desktop's Electron ABI. Extensions run inside Claude Desktop's own Electron, not the system's Node, so better-sqlite3 has to be compiled for that runtime. npm run bundle reads the Electron version out of the installed Claude.app, reinstalls the prebuilt binary for it, and then verifies what actually ships by dlopen-ing it with the packaging Node — which must fail, reporting Electron's ABI. If it loads, the Node-targeted binary slipped in and packaging aborts.

So: package on a machine running the Claude Desktop you are targeting, or pass ELECTRON_TARGET=x.y.z npm run bundle. Re-release whenever Claude Desktop bumps its Electron major — the previous bundle stops working for everyone on the new version.

1. Bump version in package.json and manifest.json (a test enforces they match).
2. npm test && npm run build && npm run bundle — the last line reports the Electron version and ABI the bundle was built for. Note it in the release description.
3. Verify the bundle:

   npx mcpb validate manifest.json
   unzip -l build/actual-budget-mcp-es.mcpb | grep -E 'tests/|docs/|\.env' | grep -v 'node_modules/'  # expect no output
   unzip -l build/actual-budget-mcp-es.mcpb | grep -c 'better_sqlite3.node'  # expect at least 1
   

   npx mcpb info <file> (CLI 2.1.2) only prints file name, size and signature status — it does not check the manifest, so it's not a substitute for validate. The node_modules/ exclusion in the grep is there because vendored dependency files aren't the project's own code and legitimately contain paths like tests/ — don't remove it.
4. Install build/actual-budget-mcp-es.mcpb locally and check it works.
5. gh release create vX.Y.Z build/actual-budget-mcp-es.mcpb, noting in the release description that the bundle targets macOS on Apple Silicon.

License

MIT — see LICENSE. Copyright (c) 2026 Marco Antonio Pérez.