actual-budget-mcp-es

**English** | [Español](README.es.md) # 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](https://actualbudget.org/) 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](#manual-installation) instead. 1. **Download** the latest `actual-budget-mcp-es.mcpb` from the [Releases page](https://github.com/marcoaperez/actual-budget-mcp-es/releases/latest). 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](#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: ```bash 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](#install-in-claude-desktop-recommended) 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: ```json { "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](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](PRIVACY.md) · [en español](PRIVACY.es.md) ## Development ```bash 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: ```bash 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](LICENSE). Copyright (c) 2026 Marco Antonio Pérez.