Actual Budget

actual-budget-mcp

[npm version] [License: MIT] [Node.js] [Glama score] [Listed on mcpservers.org]

Talk to your budget. An MCP server that connects Actual Budget to Claude. Ask where the money went, get real analysis back, and let it write without holding your breath.

Listed in the official Actual Budget community projects.

[Asking a budget where the money went, and a delete that stops to ask for confirmation]

Features

• Real analysis, not just lookups - Projections, category trends, budget vs actual, and month summaries
• Writes you can trust - Every delete previews what it will remove and waits for you to confirm; ACTUAL_READ_ONLY=1 hides the write tools from the model entirely (Safety)
• Multi-currency that survives reality - Splits and residual reconciliation, not just a currency symbol
• Recovers from an out-of-sync budget - repair_sync rebuilds the local sync state when @actual-app/api and your server disagree, the failure that otherwise leaves every tool erroring
• Ask about your budget in plain language - "How much did I spend on food this month?" or "Am I over budget on anything?"
• Create and manage transactions - Add expenses, transfers, and edits without opening the app
• Manage categories, payees, and rules - Full CRUD without opening the app
• Use names, not IDs - Say "Wallet" instead of a1b2c3d4-..., with helpful suggestions if ambiguous
• Natural dates in English and Spanish - "last month", "este mes", "hace 3 meses", "yesterday"
• Clean formatted output - Aligned tables and clear summaries, not raw JSON
• Clear error messages - If something's wrong, you'll know exactly what to fix

Does it work with local models?

Yes. This is an MCP server, so it works with any client that speaks MCP, and the model behind that client is the client's business, not this server's. Claude Desktop, Claude Code, Cursor and VS Code are the ones documented below because they are the ones people ask about, but anything that can run an MCP client, including a local setup pointed at Ollama or LM Studio, talks to it the same way.

Your budget data goes to whatever model your client uses. If that matters to you, and for a lot of people running Actual it does, a local model keeps it on your machine.

Does it work with ChatGPT?

No. ChatGPT's connectors only accept remote MCP servers: a public HTTPS endpoint speaking SSE or Streamable HTTP. With HTTP mode this server can be one. What we have read says their connectors sign in through OAuth or not at all and cannot send the fixed token header this version takes, and nobody here has tried it. OpenAI does offer a tunnel for local servers, but it is limited to enterprise plans.

Making it work would mean exposing your Actual server to the internet, which is the opposite of what most people running Actual want. Anything that can start a local MCP process works instead: Claude Desktop, Claude Code, Cursor, VS Code, Gemini CLI, or your own setup pointed at a local model.

If what you actually want is OpenAI's model, use Codex, which does run MCP servers locally over stdio. Option 6 is the one command it takes.

Prerequisites

• Actual Budget server running (local or remote)
• Node.js 22.14 or newer for every option below except the Desktop Extension (see Node.js requirement)
• The Desktop Extension needs nothing but Claude Desktop. It runs on the Node that Claude Desktop ships, and the bundle carries a SQLite binary for every platform it supports, so nothing is compiled either. Checked on Windows 11 with Claude Desktop 2.110.0 and Node removed from the machine.

Quick Start

On Claude Desktop, the shortest path is the extension: no config file to edit and no command to run. Otherwise, copy this into Claude Code or Claude Desktop:

Install the actual-budget-mcp MCP server from npm (https://github.com/henfrydls/actual-budget-mcp).Configure it with these credentials:    - My Actual Budget server: http://localhost:5006    - Password: YOUR_PASSWORD    - Budget ID: YOUR_BUDGET_ID

Claude will configure everything for you.

Installation

Option 1: Claude Desktop extension (no config files)

A packaged Desktop Extension is available: install it and Claude Desktop asks for your server URL, password and Sync ID in its own settings UI, with the password and session token stored in your operating system's keychain rather than a config file you have to edit.

Download actual-budget-mcp.mcpb, then open Claude Desktop, go to Settings > Extensions, and drag the file onto that screen.

On Windows, dragging is the way in: double-clicking the file opens Windows' "select an app to open this file" dialogue instead, because Claude Desktop does not register the .mcpb file type. Verified on a clean Windows 11 install with Claude Desktop 0.14.10.

The extension carries everything it needs, so the first question you ask is answered straight away rather than after an install you cannot see. It is a large download, once, with a progress bar.

You do not need Node.js installed for this route. Claude Desktop runs the extension on the Node it ships with. Checked by renaming Node out of the way on a Windows 11 machine and asking a question anyway: the server started and answered.

Earlier builds launched the package from npm instead. That made the download small and moved it to the first run, where nothing showed progress: Claude Desktop waited, decided the server was dead and said it could not connect, and the extension started working on its own a few minutes later. The bundle now includes Actual's SQLite binary for every platform it supports. They are N-API binaries, so one per platform serves every Node version, and nothing has to be chosen at startup.

Updating the extension

Installing a new version over an old one keeps the settings you filled in, with one exception seen in practice: the saved server password was cleared when a field's title changed between versions. If Claude cannot connect after an update, open the extension's settings and check the password field before looking anywhere else.

Option 2: Claude Code (one command)

claude mcp add actual-budget-mcp -e ACTUAL_SERVER_URL=http://localhost:5006 -e ACTUAL_PASSWORD=your-password -e ACTUAL_BUDGET_ID=your-budget-id -- npx -y actual-budget-mcp

Option 3: Claude Desktop (edit the config file)

Add this to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{  "mcpServers": {    "actual-budget-mcp": {      "command": "npx",      "args": ["-y", "actual-budget-mcp"],      "env": {        "ACTUAL_SERVER_URL": "http://localhost:5006",        "ACTUAL_PASSWORD": "your-password",        "ACTUAL_BUDGET_ID": "your-budget-sync-id"      }    }  }}

Option 4: Cursor

[Add to Cursor]

The button installs it with placeholder values. Open Cursor Settings > MCP afterwards and replace the three: your server URL, your password, and your budget's Sync ID. To do it all by hand instead, go to Cursor Settings > MCP > Add new MCP server and add:

{  "mcpServers": {    "actual-budget-mcp": {      "command": "npx",      "args": ["-y", "actual-budget-mcp"],      "env": {        "ACTUAL_SERVER_URL": "http://localhost:5006",        "ACTUAL_PASSWORD": "your-password",        "ACTUAL_BUDGET_ID": "your-budget-sync-id"      }    }  }}

Option 5: VS Code (GitHub Copilot)

[Install in VS Code] [Install in VS Code Insiders]

Same as above: the button fills in placeholders, and you replace the three values afterwards. By hand, add this to your VS Code settings.json:

{  "mcp": {    "servers": {      "actual-budget-mcp": {        "command": "npx",        "args": ["-y", "actual-budget-mcp"],        "env": {          "ACTUAL_SERVER_URL": "http://localhost:5006",          "ACTUAL_PASSWORD": "your-password",          "ACTUAL_BUDGET_ID": "your-budget-sync-id"        }      }    }  }}

Option 6: Codex (OpenAI)

One command, and it writes the entry into ~/.codex/config.toml for you:

codex mcp add actual-budget-mcp \  --env ACTUAL_SERVER_URL=http://localhost:5006 \  --env ACTUAL_PASSWORD=your-password \  --env ACTUAL_BUDGET_ID=your-budget-sync-id \  -- npx -y actual-budget-mcp

Codex has no extension or bundle format, so this one-liner is the shortest route there is. codex mcp list shows it afterwards, and codex mcp remove actual-budget-mcp undoes it.

This is Codex the local agent, the CLI and the IDE extension. Codex in the browser runs on OpenAI's machines and cannot reach an Actual server on your network.

Option 7: Docker

The image speaks stdio like every other option, so your client starts the container and owns its lifetime:

{  "mcpServers": {    "actual-budget-mcp": {      "command": "docker",      "args": [        "run", "-i", "--rm",        "--add-host=host.docker.internal:host-gateway",        "-v", "actual-budget-mcp-data:/data",        "-e", "ACTUAL_SERVER_URL",        "-e", "ACTUAL_PASSWORD",        "-e", "ACTUAL_BUDGET_ID",        "ghcr.io/henfrydls/actual-budget-mcp:latest"      ],      "env": {        "ACTUAL_SERVER_URL": "http://host.docker.internal:5006",        "ACTUAL_PASSWORD": "your-password",        "ACTUAL_BUDGET_ID": "your-budget-sync-id"      }    }  }}

Two things that bite everyone once:

• Inside the container, localhost is the container. Your Actual server is not there. host.docker.internal (with the --add-host flag above, which is what makes it resolve on Linux) reaches the host instead.
• Mount /data. That is the budget cache. Without a volume, every start re-downloads your entire budget from the server.

Option 8: From source (for contributors)

git clone https://github.com/henfrydls/actual-budget-mcp.gitcd actual-budget-mcpnpm installcp .env.example .env   # Edit with your credentialsnpm run buildnpm run test:connection # Verify it works

Verify your setup

--verify reads the environment of the shell you run it in, and the install options above put your credentials in your MCP client's configuration instead. So set them for the command:

ACTUAL_SERVER_URL=http://localhost:5006 \ACTUAL_PASSWORD=your-password \ACTUAL_BUDGET_ID=your-sync-id \npx -y actual-budget-mcp --verify

It connects, downloads the budget and prints how many accounts and category groups it found. Running it without those variables reports them as missing, which is about the command, not about your install.

After changing your client's configuration, restart the client. Claude Desktop, Claude Code and the rest read MCP configuration at startup and will not pick up an edit until they are restarted.

Running it for days at a time

Most clients start this server when you open them and stop it when you close them, and nothing below matters. If you run it as a process that stays up, an always-on chat bot or a service, it does.

The server downloads your budget once at startup and keeps a local copy. Before every read, whether you asked through a tool or read actual://accounts, it pulls whatever the Actual server has that the copy does not, so an edit you make in the Actual app shows up in the next question you ask. You do not have to restart it, and you do not have to run a bank sync to shake it loose.

Three limits keep that from costing a round trip on every call:

• A copy pulled less than 60 seconds ago is treated as current, so a burst of questions syncs once. Any sync counts, including the one a write does before deciding whether to write.
• A read waits at most 20 seconds for the pull. Past that it answers from the local copy rather than hanging, and says so.
• After a pull that fails or runs past that deadline, the next 60 seconds of reads answer straight from the local copy instead of trying again. A server that is down would otherwise charge every read the full wait, one after another.

When the pull does not happen, because the Actual server is down, unreachable or simply slow, the reply ends with a line saying it could not refresh, how old the figures are, and what went wrong:

Could not refresh from the Actual server; these figures are from the lastsync, 14 minutes ago. Anything changed in the Actual app since then may bemissing. Reason: The budget's sync state is out of sync with the Actualserver, so no operation can run until it is repaired. Run the `repair_sync`tool to rebuild the sync state (non-destructive), or repair it in the Actualapp under Settings > Show advanced settings.

That line is the point of it. A server that is down otherwise goes back to answering with figures from hours ago and nothing says which. The reason is there because these do not all want the same thing done about them: a network blip clears on its own, an out-of-sync budget has to be repaired, and a refused login needs your credentials looked at.

Writes are not affected: they already pull before the checks that decide whether to write, so they do not pay for a second one.

Each client needs its own ACTUAL_DATA_DIR. Two processes sharing one local copy will corrupt it, and a long-lived server makes that easier to do by accident, because it is there all day for a second client to point at.

Running it over HTTP

By default this server speaks stdio: the client starts it, talks to it over the pipe, and stops it. That works when the client runs on the same machine. When it does not, set ACTUAL_HTTP_PORT and the server listens instead.

Setting that port is what asks for HTTP. Nothing changes for anyone who does not set it, and the rest of the variables are read only once it is.

Two paths, two credentials

A write tool is not registered on the read path, so it cannot be called, talked into being called, or spent context on. It is the same choice ACTUAL_READ_ONLY makes, applied per path, and it means the default is a deployment that cannot change anything: without a write token there is no write path to find.

The two tokens have to differ. One credential for both paths is the same as having one path, so the server says that and does not start.

On your own machine

export ACTUAL_HTTP_PORT=3000export ACTUAL_HTTP_TOKEN="$(openssl rand -hex 16)"npx -y actual-budget-mcp

The usual ACTUAL_SERVER_URL, ACTUAL_PASSWORD and ACTUAL_BUDGET_ID are read the same way as over stdio.

openssl rand -hex 16 gives 32 characters, which is the shortest token this server will start with. The server binds to 127.0.0.1, prints one line saying where it is, and nothing outside the machine can reach it.

To be able to write as well, add a second token:

export ACTUAL_HTTP_WRITE_TOKEN="$(openssl rand -hex 16)"

Through a tunnel

A tunnel is the shortest way to reach the server from a phone or from a client that is not on your network. Both of these open an outbound connection, so nothing is forwarded into your network, and both terminate TLS for you. Keep the server on 127.0.0.1 and let the tunnel reach it there. The address the tunnel prints is what a client connects to, and the token still has to be sent with every request.

cloudflared tunnel --url http://127.0.0.1:3000

That is a quick tunnel: no account, no domain, and a trycloudflare.com address that lives as long as the process and changes every run. Cloudflare says it is for trying things out. For something you keep, create a named tunnel and point it at the same port.

tailscale funnel --bg 3000

Funnel has to be turned on for the tailnet first, in its settings. --bg keeps it running after the terminal closes.

Both of these were checked against their own documentation in October 2026. They change; the addresses and flags above are worth a look before they are copied.

On a local network

Binding anywhere other than loopback is refused unless you say that is what you meant:

export ACTUAL_HTTP_PORT=3000export ACTUAL_HTTP_HOST=0.0.0.0export ACTUAL_HTTP_ALLOW_REMOTE=1export ACTUAL_HTTP_ALLOWED_HOSTS=budget.local,192.168.1.10export ACTUAL_HTTP_TOKEN="$(openssl rand -hex 16)"

This server does not terminate TLS. Over plain HTTP on a local network the token is sent in the clear, in a header, with every request, and anyone who can see the traffic can read it and then read your budget. On a network you do not control, put a reverse proxy or a tunnel in front and let it do the encryption.

ACTUAL_HTTP_ALLOWED_HOSTS is the list of host names the server answers, without the port: budget.local, not budget.local:3000. The server takes the name out of the Host header and compares only that, so an entry with a port matches nothing and every request comes back 403. Set it whenever you bind wide: it is what keeps a page in a browser from reaching the server through a name that resolves to your machine.

What it refuses

Everything that is wrong with the configuration is printed at once, before anything is opened, so a deployment is not corrected one line and one restart at a time.

Tool results are never written to the log, at any level. What this server returns is your budget, and a log is a copy of it that nobody meant to keep.

Reaching it from claude.ai

A custom connector takes an HTTPS address, for example https://budget.example.com/mcp. The token goes in Request headers, with the scheme included, as Bearer <token>, together with No sign-in.

Anthropic's documentation says that Request headers section is in beta and available to some organisations only. Where it is not there, a static token cannot be sent and this version of the server has no other way in: sign-in through OAuth is #273 and is not in this release.

Configuration

Using a session token (OIDC servers)

If your Actual server signs you in through OIDC, there is no password to put in ACTUAL_PASSWORD, because the server issues a session token instead. Set ACTUAL_SESSION_TOKEN to that token and leave the password unset.

To find it, in the browser where you are signed in to Actual:

1. Open your browser's developer tools
2. Go to Application (Chrome/Edge) or Storage (Firefox)
3. Expand IndexedDB → the actual database → the asyncStorage store
4. Copy the value of the key user-token

It is stored in IndexedDB, not Local Storage, so looking there is why people often cannot find it.

Treat the token like a password: it grants the same access. It also expires; if it does, the server says so and tells you to issue a new one, rather than blaming a password you do not have.

Which URL and port

It depends on how you run Actual, and picking the wrong one gives a connection error that does not explain itself:

The desktop app runs its own sync server on port 5007, and only while the app is open. Close the app and nothing is listening, so the server cannot connect.

That embedded server also binds to 127.0.0.1 only. It is reachable from the same machine and from nowhere else, so if Claude runs somewhere other than the machine with the app, for example another computer or a virtual machine, you need an SSH tunnel or a port forward. Pointing at the host's LAN address will not work.

Where the cache is kept

Unless you set ACTUAL_DATA_DIR, the budget cache goes to the standard data directory for your system:

It is a cache, not your data: deleting it only forces a fresh download on the next run. It lives outside the temp directory on purpose, so a reboot does not throw it away and make the next startup re-download your whole budget.

Finding your Budget ID

1. Open Actual Budget
2. Open Settings: click the arrow next to your budget name, or use the sidebar, More, then Settings
3. Click Show advanced settings
4. Copy the Sync ID

Take the Sync ID, not the Budget ID. Actual shows both, one under the other, and they are both UUIDs. ACTUAL_BUDGET_ID wants the one labelled Sync ID, despite the name of the variable. Using the other one gives you Budget "..." not found on the server, which reads as though you mistyped it when the value was simply the wrong field.

If Sync ID shows (none), that budget has never been synced to a server. This server talks to Actual through its sync server, so a local-only budget cannot be used until you sync it.

Privacy Policy

Data collection. This server collects nothing. It has no telemetry, no analytics and no usage reporting, and none is planned: it reads personal finances, and a tool that does that should not be phoning home. There is no account to create and nothing to opt out of.

Usage and storage. The server talks to one place: the Actual Budget server whose URL you configure. Your budget is cached on your own machine, in the data directory documented under Where the cache is kept, so that it does not have to be downloaded on every start. Nothing is written anywhere else.

Your credentials are handled by your MCP client, not by this server. Claude Desktop stores the password and session token in your operating system's keychain; the server receives them as environment variables at launch, uses them to connect, and never writes them to disk.

Third-party sharing. None. No data is sent to the author, to any analytics service, or to any third party. The only network connection the server opens is to your own Actual server.

Two things worth naming because they are also true: the model you are talking to (Claude, or whichever client you use) necessarily sees the budget data you ask about, under that provider's own terms; and installing via npx downloads the package from npm, which is an ordinary package download and involves no budget data.

Data retention. The cache lives on your machine until you delete it. Deleting it loses nothing, since it is a copy of what is on your Actual server; the next run downloads it again. Uninstalling the server leaves nothing behind except that directory, which you can remove.

Contact. Open an issue at https://github.com/henfrydls/actual-budget-mcp/issues. The full policy is also published at https://actual-mcp.henfrydls.com/privacy/.

Transactions this server writes carry an id it generates

Every transaction, split and transfer created through this server is given a UUID before it is sent, and that id is what the server uses to find the row again if the write reports an error. It is the transaction's own id, not imported_id, so Actual's deduplication of imported files still works on these rows exactly as it does on any other.

Nothing about this is visible in Actual, and it changes nothing for you. It is documented because it is a real difference from writing the same transaction by hand.

Safety

Three things protect your budget from an agent acting on a vague instruction.

Deletes preview before they delete

Every delete tool refuses to destroy anything on the first call. It reports what would be lost and stops there. Deleting takes a second, deliberate call:

delete_category(category: "Groceries")  → preview: transactions affected, budget and rollover warning. Nothing deleted.
delete_category(category: "Groceries", confirm: true, confirm_name: "Groceries")  → deleted

The preview covers every row that can be deleted, which is the point of it: dated ahead of today, older than the rest of the budget, one part of a split, or in a closed account. Those four used to preview as blank and delete anyway, so the guard was asking you to confirm nothing. An id that matches no transaction is now refused rather than reported as deleted.

Tools that find their target by name (delete_account, delete_category, delete_category_group, delete_payee) also require confirm_name with the exact name. That is where deleting the wrong thing actually happens: asking for "Adicionales" can resolve to "Ingresos Adicionales". Tools that take an exact id (delete_transaction, delete_rule) need only confirm: true.

A transaction that already exists is not created twice

create_transaction looks before it writes. If the account, the date and the amount all match something already in the budget, it creates nothing and shows you what is there:

create_transaction(account: "Checking", amount: -50, date: "2026-06-05")  → A transaction like this one already exists, so nothing was created:
      2026-06-05  -50.00  Checking  Claro        id: 0b6d516e-...
    Same account, same date, same amount. If this is a second, genuine payment    rather than the same one recorded twice, call again with allow_duplicate: true.
create_transaction(account: "Checking", amount: -50, date: "2026-06-05", allow_duplicate: true)  → Transaction created

Two identical coffees on one card on one day are a real thing, so the flag exists and one extra call is the whole cost. This is a change from 0.9.x, where the second call created a second row without saying anything.

The check syncs first, so it sees what another client wrote and not only what this one did. That is the case it is for: two agents against one budget, neither able to see the other. reconcile_currency_residual takes the same flag, for the same reason, and syncs before reading the balance it computes from.

It is not returned as an error. The delete tools set isError on their preview so that a repeated call cannot destroy anything by accident. This one does the opposite, deliberately: a repeated call creates nothing at all, and an agent that reads isError treats being asked as being refused and retries, which is what duplicates. Deletes flag; this one does not.

What it costs. One extra round trip per create_transaction, whether or not a duplicate is found. Against a server on the same machine that is not measurable. Against a remote server it roughly doubles the time per write: measured at 80 ms of round-trip latency, 87 ms becomes 171 ms for a single create, and 22 creates in a row go from 1.9 s to 3.8 s. Passing allow_duplicate: true skips the sync as well as the check, so a bulk import that has already been deduplicated elsewhere pays nothing.

Offline and hung servers. If the sync fails the check still runs against the local copy and the write is not blocked, so an offline session keeps working with a weaker check rather than no writes. It says so on stderr, with the reason, so a weakened check is never silent.

A server that accepts the connection and then never answers used to be the slow case: the Actual library sets no timeout of its own, so the call fell back to Node's own five-minute header timeout, and there are two places that can happen, before the write and after it. ACTUAL_HTTP_TIMEOUT_MS, below, now ends those waits at 60 seconds by default (#99).

What it does not catch:

• A rule that rewrites the amount or the date of the row as it is stored, since the stored row then no longer matches what was asked. Renaming rules, the common kind, make no difference to it.
• A transaction that arrives between the check and the write. The sync narrows that window; it does not close it. This looks before it writes, which is not the same as doing both at once.
• create_transfer and create_split_transaction, which do not run the check yet, and an opening balance from create_account. Tracked in #98.

reconcile_currency_residual and rows that are not marked cleared

It compares against every transaction in the account up to today, which is what it has always done. A bank statement generally shows only what has posted, so if the account holds rows nobody has ticked off, the two figures may not be measuring the same thing.

It does not decide that for you. It reports it:

Currency residual reconciled:  Account:    Card (USD)  Was:        -120.00    includes 1 row not marked cleared, -20.00    cleared rows alone come to -100.00, and against that    figure the adjustment would have been 100.00.    Check which of the two the balance you gave is measuring.  Target:     0.00  Adjustment: 120.00

Nothing appears when every row is marked cleared.

Comparing against the cleared rows instead was considered and measured against a real budget first. Most rows that were not marked cleared turned out to have been sitting there for weeks, and none of them had come from a bank: they were rows nobody had ticked off, not items in flight, which clear in a day or two. Reconciling against the cleared figure would have booked all of that as an adjustment into a residual category, which is the failure this is about reached from the other side. So the figure stays as it is and you get both numbers.

reconcile_account, which writes nothing, reads the same two numbers and takes balance_counts to choose between them.

reconcile_currency_residual and dates

It refuses a date in the future for the adjustment it writes. Its whole promise is to bring the account to the balance the bank reports now, and a row that takes effect later does not do that. It also could not be made to behave: the balance counts transactions up to today, so a future-dated adjustment never entered it and every run booked another one.

"Today" here is the server's today. A client in a timezone ahead of the server can be told its own date is in the future; omitting date, or passing "today", uses the same clock as the check and always works. create_transaction has no such restriction, so recording a purchase dated ahead, which is what you want when a card posts a weekend purchase on the next business day, still works there.

When the account holds transactions dated after today, it asks which they are. Actual's balance stops at today; your bank's figure may not. A card purchase made at the weekend is commonly posted with the following business day's date, so the bank has already counted something the balance has not, and the difference would otherwise be booked as currency drift.

So reconcile reports those rows and books nothing until you say which reading you gave it:

reconcile_currency_residual(account: "Card", target_balance: -140, category: "Cashback")  → No adjustment was booked for Card.
    This account holds 2 transactions dated after today, so the balance Actual    reports and the balance your bank reports are not measuring the same thing.
      2026-09-28  -40.00  WEEKEND-PURCHASE  (came from the bank, so the bank counts it)      2026-10-26  -80.00  SCHEDULED-LATER
      Balance to today:        -100.00      Those rows come to:      -120.00      Balance counting them:   -220.00      You said the bank says:  -140.00
    Which is it?
      future_rows: "exclude"   the bank has not posted them yet.                               Adjustment would be -40.00.      future_rows: "include"   the bank has posted them already, ...                               Adjustment would be 80.00.

The choice is yours, because in general nothing says which a row is. Where something does, it is said: a row that arrived from the bank is one the bank obviously counts, and a row entered here and not reconciled may be one it has not seen. Neither settles it, both narrow it. Rows are listed oldest first, so the nearest one, the one most likely to have been posted, is the first you read.

Accounts with nothing dated ahead are unaffected and never see the question. A row dated exactly today counts as present, not as ahead, because the balance already includes it.

Whichever you choose is recorded on the adjustment itself, as FX residual adjustment (counting 2 transactions dated after today), so a row booked on the wrong reading can be found later instead of being a puzzle.

Measured before this existed: an account at -100.00 to today, a -40.00 purchase dated ahead that the bank had posted, a -80.00 transfer scheduled for later that it had not, and a bank figure of -140.00. It booked -40.00 and left the account summing to -260.00 where the bank ends at -220.00. The adjustment was exactly the purchase, recorded a second time, in a category that calls it drift.

It also refuses a date that does not exist, such as 2026-09-31 or 2026-02-30, rather than calling it a future one. Other tools still accept an impossible date and store it verbatim; that is older than this and unchanged.

It also syncs three times on the happy path: once before reading the balance, once inside the create it delegates to, and once to push. Two of those are consecutive pulls, so a remote server pays a redundant round trip.

Read-only mode

Set ACTUAL_READ_ONLY=1 and the server exposes only the 17 read, analysis and repair tools. The write tools are not registered at all, so they never appear in tool discovery, and an agent cannot be talked into calling something it cannot see.

repair_sync stays available on purpose: it repairs sync state rather than budget data, and hiding it would leave a desynced budget with no way to recover.

Writes are enabled by default. Read-only is opt-in.

More than one budget

One budget is the default and needs nothing: ACTUAL_BUDGET_ID is the sync id of the budget this server opens, and no tool asks which budget a call is for, because there is nothing to choose.

ACTUAL_BUDGET_IDS lists every budget the server serves, comma separated, when there is more than one. Two things appear when it is set, and only then:

• A tool called list_budgets, which names them by the sync id a caller passes, with the open ones marked. A budget's own name is inside its file, so it appears once the budget has been opened at least one time, and stays afterwards: one that has never been opened is listed by id alone. It lists what you configured and nothing else: a budget on the account that is not in the list cannot be reached by asking for its id.
• An optional budget_id on every tool. Left out, a call is for the budget in ACTUAL_BUDGET_ID.

The Actual library opens one budget per process, so the server opens a child process per budget and routes each call to the one that holds it. Three stay open at once by default, and a fourth budget closes the one that went longest without a call, never one with a call in flight. A budget that goes 15 minutes without a call closes on its own. ACTUAL_BUDGET_WORKERS and ACTUAL_WORKER_IDLE_MINUTES change those two numbers.

Opening a budget takes about a second on a small file, so the first call for a budget waits. If it is still not open after ACTUAL_WORKER_READY_SECONDS, the call answers that the budget is still opening and asks you to try again, rather than hanging past the client's own one minute timeout. For a write, the answer says that nothing was sent to the budget, so repeating it cannot write twice.

When every budget this server keeps open is busy, a call for another one waits for room and is then told that everything is busy, in the same words and with the same promise: nothing was read or written, and nothing was sent. A write that takes longer than this server waits for one is the other way round, and says so plainly: the worker is still applying it, so check the budget before repeating it rather than sending it twice.

list_budgets is where a deployment with several budgets finds out what it is talking to. Each budget is listed with the name its own worker read out of the file, [open] while a worker holds it and (closed) once that worker has gone, and a budget nobody has opened yet is listed by its id alone. If a worker found that your Actual server and this server's Actual library differ on major or minor, the line says which budget that was and both versions, and one sentence at the end says what it means. Nothing refuses to open over it: Actual's minor is the month, so a server that updates itself is a minor ahead of this one every time Actual releases.

The resources (actual://accounts and the other two) are not offered when there is more than one budget. A resource is a URI and nothing else: it has nowhere to say which budget it is about, and answering from the default one would be a second, quieter answer that contradicts the tools. The tools take budget_id, so they are the one way to ask.

Each budget gets its own directory under ACTUAL_DATA_DIR, named after its sync id, so the ids have to be ids: a list with a path in one of them is refused at startup rather than writing a budget cache somewhere else. Two processes cannot share one budget cache. If more than one of the budgets is encrypted, ACTUAL_ENCRYPTION_PASSWORDS maps sync id to password:

{"budget-sync-id-one": "first password", "budget-sync-id-two": "second"}

Each budget is given its own password and nothing else: the map itself never reaches the processes that open the budgets. With one encrypted budget, ACTUAL_ENCRYPTION_PASSWORD on its own still works.

Both the tool and the parameter cost context on every connection, so neither appears when there is one budget. Measured with two budgets configured, the full set goes from 39.7 KiB to 47.6 KiB of tool descriptions, which is 7.9 KiB more, a fifth again. With ACTUAL_BUDGET_IDS unset, what a client is sent is byte for byte what it was sent before any of this: no extra tool, no extra parameter, and no child process.

Serving them to more than one client

Several budgets and HTTP mode are the same deployment in practice: one server somewhere that several people, or several clients, point at. The two work together without anything new. The read path and the write path are the same process, the budget each call is for is the budget_id it names, and which tools exist is decided per path, so a credential that may only read cannot write in any budget rather than in some of them.

What a worker is started with is built rather than inherited, which matters once this runs in a container: TZ, the proxy variables and the certificate paths are passed down, because they are facts about the machine and a budget is full of dates, while the HTTP port and its credentials are not, because a worker has no door of its own.

In Docker, with a volume

# compose.yamlservices:  actual-budget-mcp:    image: ghcr.io/henfrydls/actual-budget-mcp:latest    restart: unless-stopped    ports:      - "127.0.0.1:3000:3000"    volumes:      - actual-budget-mcp-data:/data    environment:      ACTUAL_SERVER_URL: http://actual:5006      ACTUAL_PASSWORD: ${ACTUAL_PASSWORD}      ACTUAL_BUDGET_ID: first-budget-sync-id      ACTUAL_BUDGET_IDS: first-budget-sync-id,second-budget-sync-id      ACTUAL_HTTP_PORT: "3000"      ACTUAL_HTTP_HOST: "0.0.0.0"      ACTUAL_HTTP_ALLOW_REMOTE: "1"      ACTUAL_HTTP_ALLOWED_HOSTS: "localhost,127.0.0.1"      ACTUAL_HTTP_TOKEN: ${ACTUAL_HTTP_TOKEN}      ACTUAL_HTTP_WRITE_TOKEN: ${ACTUAL_HTTP_WRITE_TOKEN}      TZ: America/Santo_Domingo
volumes:  actual-budget-mcp-data:

The volume is the point of the whole file. ACTUAL_DATA_DIR is /data in the image, each budget gets its own directory under it, and without somewhere to keep them every restart downloads every budget again. Binding the port to 127.0.0.1 keeps it on the host; ACTUAL_HTTP_HOST=0.0.0.0 is about the inside of the container, where 127.0.0.1 would be unreachable from anywhere, and ACTUAL_HTTP_ALLOW_REMOTE=1 is this server asking you to mean it. Off loopback it also wants ACTUAL_HTTP_ALLOWED_HOSTS: the hostnames clients put in the Host header, without ports, since the check ignores the port. Get it wrong and every request comes back 403 Invalid Host, which is the failure that looks like a broken token. Both tokens are at least 32 characters.

In Kubernetes

The same thing, with four things worth knowing before you write the manifest:

• One replica. Two processes sharing one budget cache is what drives a budget out of sync, so a second replica on the same volume does not share it: it steps aside to a directory of its own and downloads everything again. If you need more throughput, give each replica its own volume and its own budgets, not a copy of the same ones.
• The image runs as uid 1000 (node), so the volume needs securityContext: {runAsUser: 1000, fsGroup: 1000} or the first write to /data fails.
• Probe the port, not a path. Every path answers 401 without a credential, by design, so a tcpSocket probe is the honest one. An httpGet probe works too if you treat 401 as healthy.
• Size it per budget that stays open. ACTUAL_BUDGET_WORKERS is how many processes hold a budget at once, each one a Node process with a budget in it, so the memory this needs is that number times one budget, not one.

apiVersion: apps/v1kind: Deploymentmetadata:  name: actual-budget-mcpspec:  replicas: 1  strategy:    type: Recreate  selector:    matchLabels: {app: actual-budget-mcp}  template:    metadata:      labels: {app: actual-budget-mcp}    spec:      securityContext:        runAsUser: 1000        fsGroup: 1000      containers:        - name: server          image: ghcr.io/henfrydls/actual-budget-mcp:latest          ports:            - containerPort: 3000          env:            - {name: ACTUAL_SERVER_URL, value: http://actual:5006}            - {name: ACTUAL_BUDGET_ID, value: first-budget-sync-id}            - {name: ACTUAL_BUDGET_IDS, value: "first-budget-sync-id,second-budget-sync-id"}            - {name: ACTUAL_BUDGET_WORKERS, value: "2"}            - {name: ACTUAL_HTTP_PORT, value: "3000"}            - {name: ACTUAL_HTTP_HOST, value: "0.0.0.0"}            - {name: ACTUAL_HTTP_ALLOW_REMOTE, value: "1"}            - {name: ACTUAL_HTTP_ALLOWED_HOSTS, value: "actual-budget-mcp,mcp.example.internal"}            - {name: TZ, value: America/Santo_Domingo}          envFrom:            - secretRef: {name: actual-budget-mcp}          readinessProbe:            tcpSocket: {port: 3000}          volumeMounts:            - {name: data, mountPath: /data}      volumes:        - name: data          persistentVolumeClaim: {claimName: actual-budget-mcp}

ACTUAL_HTTP_ALLOWED_HOSTS is the names clients actually use, without ports: the Service name inside the cluster, and whatever host an Ingress answers to. The Secret holds ACTUAL_PASSWORD, ACTUAL_HTTP_TOKEN, ACTUAL_HTTP_WRITE_TOKEN and, if your budgets are encrypted, ACTUAL_ENCRYPTION_PASSWORDS. strategy: Recreate rather than a rolling update, for the same reason there is one replica: during a rollout the old pod still holds the volume.

Choosing a toolset

Every connection is sent the whole tool list before anything is asked. Measured with scripts/measure-toolset.mjs, which registers the real tools and asks a real client for tools/list:

chat is the everyday set: reading the budget, recording and categorising transactions, and moving budgeted money between categories. What it leaves out is setting up and repairing a budget, which is creating and deleting accounts, categories, groups, payees and rules, along with reconcile_currency_residual and repair_sync.

It is worth setting for two reasons, and the second is the bigger one: the context is spent whatever the conversation turns out to be about, and a model choosing between 44 descriptions picks the wrong tool more often than one choosing between 18.

The prompts go with the tools they call. Each one is a short script naming three or four tools, so a prompt whose tools are not offered is not offered either. With chat that leaves none of them, and a server with no prompts does not advertise prompts at all: prompts/list answers that the method is not supported, rather than with an empty list.

The two settings narrow together rather than fighting: read-only decides which tools exist, ACTUAL_TOOLSET decides which of those are offered.

Tools (44)

Read (11)

Analysis (5)

Write: Transactions (11)

Write: Categories (6)

Write: Payees & Rules (5)

Write: Accounts (3)

delete_account needs two keys. It destroys the account's entire transaction history, so a single call never deletes. The first call only previews what would be lost (name, balance, transaction count) and suggests closing the account instead, since closing retires it while keeping its history. To actually delete, call again with confirm: true and confirm_name set to the account's exact name. While it declines, the tool reports isError: true, so a confirmation prompt is never mistaken for a completed deletion.

Maintenance (1)

If tools start failing with a sync error, the budget's sync state is inconsistent with the server. repair_sync rebuilds that state without touching budget data. Note that deleting the local ACTUAL_DATA_DIR does not fix this, because the inconsistency is in the sync state, not the cache.

It checks the server is there first. Two different problems fail the same way: a broken sync state, and a server that is not running — which for the desktop app means the app is closed, since its server on port 5007 only runs while it is open. repair_sync only fixes the first, so if nothing is listening it says so and changes nothing, rather than spending a repair on a problem that is "the app is not running".

Prompts

Built-in prompt templates that guide Claude through multi-step financial analysis:

Use them in Claude Desktop by clicking the prompt icon, or in Claude Code by asking Claude to use them.

Resources

Pre-loaded data that Claude can reference without calling tools:

Usage Examples

Here are real prompts you can use:

"How much did I spend in February?"
"Show me my top 5 spending categories this month"
"Am I over budget on anything?"
"I spent 1,200 on electricity from my checking account yesterday"
"What's my savings rate this month?"
"Show me all transactions from Wallet in the last 30 days"
"Transfer 5,000 from Checking to Savings"
"What are my spending trends for food over the last 6 months?"
"Create a category called Gym in Variable Spending"
"Rename the Gym category to Fitness"
"Create a rule: when payee is Netflix, set category to Suscripciones"
"How have my finances been the last 3 months?"

How is this different?

Compared to other Actual Budget MCP servers:

Security

• This server connects to your Actual Budget instance using the credentials you provide
• Credentials are passed as environment variables and never stored by the MCP server
• All communication with your Actual Budget server happens locally (or to your self-hosted server)
• The server only accesses budget data through the official @actual-app/api library
• No data is sent to third parties
• Over HTTP a bearer token is required, at least 32 characters, compared in constant time, and a request from a browser is refused outright
• This server does not terminate TLS. On anything other than loopback, put a reverse proxy or a tunnel in front of it, or the token travels in the clear

Troubleshooting

Stuck on something that is not listed here? Tell me what tripped you up. A sentence is enough, and a failed setup looks identical to no setup at all from my side.

"Could not connect to Actual Budget server"

• Make sure Actual Budget is running (open the app or start the server)
• Check that ACTUAL_SERVER_URL is correct
• Run npx -y actual-budget-mcp --verify to test your connection

"Authentication failed"

• Your server requires a password. Set ACTUAL_PASSWORD in your config
• If you forgot the password, reset it in Actual Budget under Settings > Server

"Budget not found"

• Check your ACTUAL_BUDGET_ID. Find it in Settings > Show advanced settings > Sync ID

"Budget file is encrypted"

• Set ACTUAL_ENCRYPTION_PASSWORD with your encryption password

"Ambiguous name: matches X, Y"

• Be more specific. Instead of "Main", try "Main Checking" or "Main Savings"

Node.js Requirement

The server exits immediately, or dies with no message at all

• From 0.10.1 the minimum is Node 22.14. Actual's SQLite library is built against N-API 10, which arrives in that release; on an older Node the binary loads and then segfaults when the budget is opened. Measured on 22.13.1: exit code 139, no message, no stack, nothing in any log. A host that restarts the server would do it forever.
• The server now checks this at startup and says so instead of crashing, but only from 0.10.1 on.
• Solution: run Node 22.14 or newer, or use the Docker image, which carries its own.

"ReferenceError: navigator is not defined"

• @actual-app/api referenced the navigator global through 26.6. That global only exists on Node.js 21+, so importing the library on Node.js 20 threw before the server could start. 26.8 dropped the reference.
• Solution: Run Node.js 22.14 or newer.

Your Actual apps stop opening the budget after using this server

• Opening a budget runs any migration the library has and the file does not, and the next sync uploads the result. From 0.10.1 this server carries Actual 26.10, so pointing it at a 26.9 server migrates the budget to the newer format, and an Actual app still on 26.9 then cannot open it. Measured: 59 migrations become 60.
• Actual's own apps do exactly the same when they update; the difference is that this one can reach your budget before you have updated anything else.
• The other direction is the same problem seen from the other end: an Actual server ahead of this server's library holds a budget that may carry migrations the library does not have, and a tool then fails with a message about a file rather than about a version.
• The server says so on startup, before it downloads anything, whichever of the two is behind, and list_budgets says it again in its answer, because a server your client starts in the background has nobody reading its log. It says it and opens the budget anyway: Actual's minor is the month, so a server that updates itself is a minor ahead of this one every time Actual releases, and refusing to work on that would be worse than the warning.
• Solution: keep your Actual server and this server on the same Actual version. If you have already hit it, update whichever is behind and the budget opens again, with nothing lost.

"version `GLIBC_2.34' not found", or the budget never opens on an older Linux

• Actual's SQLite binary for Linux is built against glibc 2.34, so it does not load on Debian 11, Ubuntu 20.04 or RHEL 8, whose glibc is older. Measured against Debian 11's libc: version 'GLIBC_2.33' not found.
• There is no override for this: a package.json override does not reach an npx install, and the binary is what the library ships.
• Solution: run the Docker image, which carries its own glibc, or a distribution with glibc 2.34 or newer (Debian 12, Ubuntu 22.04, RHEL 9).

"gyp ERR! find Python" when installing from source

• Installing from a clone runs npm ci, and npm builds any package that ships a binding.gyp, which better-sqlite3 does even though it needs no building: the binary it uses is already in the package.
• Solution: npm ci --ignore-scripts. Nothing is lost; that is what the extension and the Docker image do.

Node Version Managers (fnm, nvm, volta)

MCP server shows "Server disconnected" in Claude Desktop

• Claude Desktop doesn't source your shell profile (.bashrc, .zshrc), so version managers like fnm, nvm, and volta won't work with the default npx command. This applies to a manual npx entry in the config file, not to the Desktop Extension, which carries its own dependencies.
• Solution: Use the absolute path to node in your config. Find it with:

readlink -f $(which node)

Then update your claude_desktop_config.json:

{  "mcpServers": {    "actual-budget-mcp": {      "command": "/home/user/.local/share/fnm/node-versions/v22.22.1/installation/bin/node",      "args": ["/path/to/actual-budget-mcp/dist/index.js"],      "env": {        "ACTUAL_SERVER_URL": "http://localhost:5006",        "ACTUAL_PASSWORD": "your-password",        "ACTUAL_BUDGET_ID": "your-budget-sync-id"      }    }  }}

Alternatively, create a wrapper script mcp-wrapper.sh:

#!/bin/bashexport PATH="$HOME/.local/share/fnm/node-versions/v22.22.1/installation/bin:$PATH"exec npx -y actual-budget-mcp "$@"

Then use it in your config:

{  "mcpServers": {    "actual-budget-mcp": {      "command": "/path/to/mcp-wrapper.sh"    }  }}

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

git clone https://github.com/henfrydls/actual-budget-mcp.gitcd actual-budget-mcpnpm installnpm run buildnpm test               # Run unit testsnpm run test:connection # Needs .env configured

License

MIT - DLSLabs