balance-history
Get account balance history over time
LABSCO SUMMARY
Budget questions get answered from the ledger instead of from a spreadsheet export.
The analysis tools do the arithmetic for you — spending by category, monthly income against expenses, balance history — which is what makes this usable in conversation rather than as a table dump. The write side is opt-in and complete enough to deserve that: transactions, categories, payees and rules can all be deleted, and a deleted transaction does not come back. Start it without --enable-write while you are getting a feel for it, and reach for the import tool rather than create-transaction for anything arriving in bulk, since it reconciles on imported_id and will show you the result under a dry run first.
What it is
A server over an Actual Budget file, covering transactions, categories, payees, rules and bank sync, with the write half kept behind a launch flag.
What you get
- Answers rather than rows: spending broken down by category over a date range, monthly income against expenses and savings, and balance history per account
- Transaction reads filtered by date range, amount range, payee name and category name in the same call
- A complete write path on transactions — create, delete, and update covering date, amount, payee, category, notes, cleared status and subtransactions
- Bulk import with reconciliation: a repeated import deduplicates on imported_id rather than doubling up, and a dry run previews the change before anything persists
- Budget structure as editable objects — categories, category groups, payees and rules each with create, update and delete
- Bank synchronisation through GoCardless or SimpleFIN for one account, for the on-budget or off-budget group, or across every linked account
Requirements
Node 16 or newer and an Actual Budget you can reach: ACTUAL_SERVER_URL and ACTUAL_PASSWORD for a remote server, ACTUAL_BUDGET_SYNC_ID for the budget file to open, and ACTUAL_DATA_DIR for the local cache, which is optional when a server URL is set. An encrypted budget takes its unlock password separately in ACTUAL_BUDGET_ENCRYPTION_PASSWORD. Every write tool stays hidden until the server is started with --enable-write. Bank sync needs the account already linked in Actual. Amounts are in cents, positive for a deposit and negative for a payment. MIT.
Setup effort
One command — docker pull sstefanov/actual-mcp:latest
USE CASES
01
Finding out why last month cost more
Break the range down by category, compare it against the months either side, then pull the transactions behind whichever category moved.
02
Cleaning up a miscategorised import
Pull the transactions that landed in the wrong place, read the category groups to find where they belong, and set the category on each one.
03
Pulling in a statement without duplicating rows
Check which account you are importing into, run the import as a dry run to see what it would do, then let it reconcile on imported_id — or trigger the bank sync and skip the file entirely.
04
Making a recurring payee categorise itself
Find how the payee is recorded, read the rules already in place so the new one does not contradict them, and add the rule with its conditions and actions.
05
Reshaping the budget's categories
Read the current groups, add the group the new structure needs, create categories inside it, and move the existing ones over by updating their group.
25 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
create-category
Create a new category
create-category-group
Create a new category group
create-payee
Create a new payee
create-rule
Create a new rule
create-transaction
Create a new transaction. Use this to add transactions to accounts. Supports transfers between accounts by specifying transfer_account_id.
delete-category
Delete a category
delete-category-group
Delete a category group
delete-payee
Delete a payee
delete-rule
Delete a rule
delete-transaction
Delete a transaction by its ID. This action is permanent and cannot be undone.
get-accounts
Retrieve a list of all accounts with their current balance and ID.
get-grouped-categories
Retrieve a list of all category groups with their id, name, type and category list.
get-payees
Retrieve a list of all payees with their id, name, categoryId and transferAccountId.
get-rules
Retrieve a list of all rules. PS amount comes in cents: positive for deposit, negative for payment
get-transactions
Get transactions for an account with optional filtering
import-transactions
Import a list of transactions into an account using reconciliation logic. Deduplicates via imported_id to prevent duplicates on repeated imports. Supports dry-run mode to preview changes without persisting them.
monthly-summary
Get monthly income, expenses, and savings
run-bank-sync
Run bank synchronization (GoCardless/SimpleFIN) to download latest transactions. Provide accountId for a specific account, use "onbudget"/"offbudget" for groups, or omit to sync all linked accounts.
spending-by-category
Get spending breakdown by category for a specified date range
update-category
Update a category
update-category-group
Update a category group
update-payee
Update a payee
update-rule
Update a rule
update-transaction
Update an existing transaction. Can modify date, amount, payee, category, notes, cleared status, and subtransactions.
BEFORE YOU INSTALL
What to know first
Tools you get
25 tools when we connected. That count assumes --enable-write; without it the write tools don't load. import-transactions, which loads a bank statement, plus delete-transaction and run-bank-sync are missing from the documented feature list.
Requires
npx on PATH
CONTEXT COST
Moderate Standing cost
Rated by the size of the 25 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
docker pull sstefanov/actual-mcp:latestMCP Clients
Claude Desktop — npx
CLAUDE DESKTOP — NPX · JSON
{
"mcpServers": {
"actualBudget": {
"command": "npx",
"args": [
"-y",
"actual-mcp",
"--enable-write"
],
"env": {
"ACTUAL_DATA_DIR": "<YOUR_ACTUAL_DATA_DIR>",
"ACTUAL_PASSWORD": "<YOUR_ACTUAL_PASSWORD>",
"ACTUAL_SERVER_URL": "<YOUR_ACTUAL_SERVER_URL>",
"ACTUAL_BUDGET_SYNC_ID": "<YOUR_ACTUAL_BUDGET_SYNC_ID>"
}
}
}
}Claude Desktop — local build
CLAUDE DESKTOP — LOCAL BUILD · JSON
{
"mcpServers": {
"actualBudget": {
"command": "node",
"args": [
"<YOUR_PATH_TO_CLONE>/build/index.js",
"--enable-write"
],
"env": {
"ACTUAL_DATA_DIR": "<YOUR_ACTUAL_DATA_DIR>",
"ACTUAL_PASSWORD": "<YOUR_ACTUAL_PASSWORD>",
"ACTUAL_SERVER_URL": "<YOUR_ACTUAL_SERVER_URL>",
"ACTUAL_BUDGET_SYNC_ID": "<YOUR_ACTUAL_BUDGET_SYNC_ID>"
}
}
}
}Claude Desktop — Docker
CLAUDE DESKTOP — DOCKER · JSON
{
"mcpServers": {
"actualBudget": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v",
"<YOUR_PATH_TO_DATA>:/data",
"-e",
"ACTUAL_PASSWORD=<YOUR_ACTUAL_PASSWORD>",
"-e",
"ACTUAL_SERVER_URL=<YOUR_ACTUAL_SERVER_URL>",
"-e",
"ACTUAL_BUDGET_SYNC_ID=<YOUR_ACTUAL_BUDGET_SYNC_ID>",
"sstefanov/actual-mcp:latest",
"--enable-write"
]
}
}
}Codex
CODEX · TERMINAL
git clone https://github.com/s-stefanov/actual-mcp.git
cd actual-mcp
npm install
npm run buildIn the same terminal, export ACTUAL_SERVER_URL, ACTUAL_PASSWORD and ACTUAL_BUDGET_SYNC_ID (or ACTUAL_DATA_DIR for a local budget), as in the README's environment step
CODEX · TERMINAL
npm start -- --sse --port 3000Keep that terminal open, then add this to ~/.codex/config.toml:
CODEX · TOML
[mcp_servers.actual-budget]
url = "http://localhost:3000"The url must use the port you passed to npm start. Add --enable-write to the npm start line if you want the write tools.
