Skip to main content
Glama
MCP Actual

MCP Actual

by cubicecho

MCP Actual

An MCP server for Actual Budget. It connects to your Actual sync server, opens one budget file, and exposes it to MCP clients over streamable HTTP (/mcp) or stdio.

Tools

Read-only tools are always served. Tools marked ✏️ modify the budget and are served only when ACTUAL_ENABLE_WRITES is on (the default) — when it is off they are not advertised at all.

Accounts & context

Tool

Description

list_accounts

Every account with its current balance, plus on-budget and overall totals.

list_categories

Categories with their groups. Most budgeting and rule work starts here.

resolve_name_to_id

Exact-name lookup for accounts, categories, payees, and schedules.

list_schedules

Scheduled (recurring) transactions and their next due dates.

list_tags

Tags available to rules that match note tags.

get_note

Read the note attached to any entity.

sync_budget

Pull the latest changes from the Actual server.

update_note

✏️

Replace an entity's note.

run_bank_sync

✏️

Fetch new transactions from linked banks.

Transactions

Tool

Description

search_transactions

Cross-account search by date, account, payee, category, notes, amount, and cleared state.

get_transactions

Every transaction in one account between two dates, uncapped.

update_transaction

✏️

Change a transaction's category, payee, notes, cleared flag, date, or amount.

Payees

Tool

Description

list_payees

Payees with transaction counts and last-used dates.

find_duplicate_payees

Cluster near-identical payee names into merge candidates. Suggests only.

create_payee

✏️

Create a payee.

update_payee

✏️

Rename a payee.

merge_payees

✏️

Merge payees into a target. Cannot be undone.

Rules

Tool

Description

describe_rule_schema

The exact rule format: fields, legal operators, and examples. Call before authoring a rule.

list_rules

All rules, or only those for one payee.

create_rule

✏️

Create a rule from conditions and actions.

update_rule

✏️

Replace a rule wholesale.

preview_rule_effects

What the rules would change on real transactions, saving nothing. Reports the whole rule set, not one rule.

apply_rule_actions

✏️

Apply actions to an explicit list of transaction ids (max 500) and save.

Budgets

Tool

Description

list_budget_months

Every month the budget file covers.

get_budget_month

One month's totals and per-category budgeted/spent/balance.

set_budget_amount

✏️

Set a category's budgeted amount for a month.

set_budget_carryover

✏️

Roll a category's balance into the next month, or stop.

hold_for_next_month

✏️

Hold surplus back for next month.

reset_budget_hold

✏️

Release a held amount.

list_category_groups

Groups with their ids and category counts — the only way to see an empty group.

create_category

✏️

Create a category in a group.

update_category

✏️

Rename, move, or hide a category.

create_category_group

✏️

Create an empty group to file categories under.

update_category_group

✏️

Rename a group, or hide/unhide it and everything in it.

There are no delete tools — see TODO_IDEAS.md. All amounts are integer cents (amount), with a decimal sibling (amountDecimal) for display; tools accept integers only.

Example list_accounts result:

{
  "accounts": [
    {
      "id": "729cb...",
      "name": "Checking",
      "amount": 123456,
      "amountDecimal": 1234.56,
      "offBudget": false,
      "closed": false
    }
  ],
  "onBudgetTotal": 123456,
  "total": 123456
}

Totals cover open (non-closed) accounts; onBudgetTotal excludes off-budget tracking accounts. The budget is synced with the server before every read.

Related MCP server: ynab-mcp-bridge

Prompts

The server exposes MCP prompts, so a client can pull a vetted workflow instead of you writing one. Start with explore_budget.

Prompt

Arguments

explore_budget

question

What the budget holds and which tool answers what. The orientation prompt.

categorize_transactions

period

Triage uncategorized spending by payee, propose a category for each, apply what you approve.

cleanup_payees

focus

Group duplicate merchant names ("AMZN Mktp US*2H4" vs "Amazon"), review, merge on confirmation.

backfill_rule

goal, scope

Apply a rule to transactions that already exist: author it, preview what changes, confirm, then apply.

Every argument is optional — the prompt asks rather than guessing — and the prompts are available whether or not writes are enabled. With ACTUAL_ENABLE_WRITES off they render a read-only variant that stops after the analysis instead of vanishing, so the agent is told writing is unavailable rather than left to improvise.

Prefer these over driving the sharp tools yourself: apply_rule_actions applies actions unconditionally and merge_payees cannot be undone, and the prompts are what enforce previewing and confirming first.

What you need before you start

You need three things, and nothing else. There is no API key and no username — an Actual sync server authenticates with a single password, and the budget is selected by its Sync ID.

  1. A running Actual sync server and its URL, e.g. https://budget.example.com or http://192.168.1.50:5006 — the same URL you open the Actual web UI at.

  2. The server password — what you type on the Actual login screen.

  3. The budget's Sync ID — open Actual → Settings → Advanced settings → "Sync ID". It is a UUID like a1b2c3d4-….. This is not the budget's display name and not the My-Finances-xxxx folder name.

Plus Node.js ≥ 22.18, or Docker.

Configuration

All configuration is environment variables — copy .env.example to .env and fill in the three required values. docker compose reads that same .env.

Variable

Required

Default

What to put in it

ACTUAL_SERVER_URL

✅

—

Base URL of the Actual sync server, scheme included, no trailing path

ACTUAL_PASSWORD

✅

—

The sync server's login password

ACTUAL_SYNC_ID

✅

—

Actual → Settings → Advanced settings → "Sync ID"

ACTUAL_ENCRYPTION_PASSWORD

—

Only if the budget has end-to-end encryption enabled

MCP_ACTUAL_TOKEN

✅*

—

Bearer token clients must send to /mcp. *Required unless SECURE_LOCAL_NET=true

SECURE_LOCAL_NET

—

true runs with no auth at all (trusted networks only)

ACTUAL_TIMEOUT_MS

120000

Deadline for one Actual operation; bank sync gets its own, longer one

ACTUAL_ENABLE_WRITES

true

false serves only read-only tools; write tools are not advertised at all

DATA_DIR

./data (/data in Docker)

Where the downloaded budget is cached

PORT

3000

HTTP port

HTTP_KEEP_ALIVE_TIMEOUT_MS

75000

How long an idle client connection is kept open. Above the 60 s nginx and ALB hold theirs; raise it behind a proxy that holds longer. 0 never closes one

MCP_LAN_ADVERTISE

false

true announces the server on the local network over mDNS; see Network discovery

Missing or malformed values are reported at startup with every offending variable named at once.

Pointing at an Actual server that also runs in Docker: use its service name (http://actual_server:5006) and put both on the same Docker network. Inside this container, localhost is this container, not your host.

Running

Local

npm install
cp .env.example .env   # fill in your server URL, password, and sync id
npm run build
npm start              # HTTP server on :3000, MCP at /mcp

Docker

cp .env.example .env    # fill in ACTUAL_SERVER_URL, ACTUAL_PASSWORD, ACTUAL_SYNC_ID
docker compose up -d
docker compose logs -f  # confirm it opened the budget

Compose refuses to start with a message naming any required variable you left unset. ./data is mounted at /data so the downloaded budget survives restarts.

Without compose, the same three variables must be passed explicitly:

docker run -d --name mcp-actual -p 3000:3000 \
  -v "$PWD/data:/data" \
  -e ACTUAL_SERVER_URL=https://budget.example.com \
  -e ACTUAL_PASSWORD='your-actual-password' \
  -e ACTUAL_SYNC_ID=00000000-0000-0000-0000-000000000000 \
  -e MCP_ACTUAL_TOKEN="$(openssl rand -hex 32)" \
  mcp-actual

Published images: ghcr.io/<owner>/mcp-actual and Docker Hub <dockerhub-user>/mcp-actual, tagged latest and by semver.

Connecting a client

Streamable HTTP — point the client at http://<host>:3000/mcp, sending Authorization: Bearer $MCP_ACTUAL_TOKEN if a token is configured.

stdio — for local clients such as Claude Code:

{
  "mcpServers": {
    "actual": {
      "command": "node",
      "args": ["/path/to/mcp-actual/dist/stdio.js"],
      "env": {
        "ACTUAL_SERVER_URL": "https://budget.example.com",
        "ACTUAL_PASSWORD": "…",
        "ACTUAL_SYNC_ID": "…",
        "DATA_DIR": "/path/to/mcp-actual/data"
      }
    }
  }
}

Or, after npm link, use the mcp-actual-stdio binary.

GET /api/status is an unauthenticated liveness probe (name, version, and the configured Actual server URL) used by the Docker healthcheck.

Network discovery

The server describes its MCP endpoint so other tools, such as mcp-router, can find it without being given the URL:

  • GET /.well-known/ai-catalog.json is an AI Catalog listing /mcp.

  • GET /mcp/server-card describes it (MCP Server Card): its name, version, URL, and whether a bearer token is required.

These are public, with no token needed. They say an Authorization header is required when auth is on, but never carry the token, the Actual server URL or anything from the budget. Both come from @cubicecho/mcp-discovery.

MCP_LAN_ADVERTISE=true (off by default) also announces the server over mDNS as an _mcp._tcp service named MCP Actual on <hostname>, so it can be found without knowing its address. Connecting still needs the token. mDNS needs multicast, which Docker's default bridge network drops: in a container, use network_mode: host (commented out in docker-compose.yml) for the announcement to reach the LAN.

Security notes

  • The server holds your Actual password and reads your full financial data. It refuses to start without MCP_ACTUAL_TOKEN, unless you set SECURE_LOCAL_NET=true to say an unauthenticated server is what you intended. An unset variable looks exactly like a misspelled one, so the old behaviour — start anyway and warn — turned a single typo into an open server.

  • Writes are on by default. An agent connected to this server can change categories, rename and merge payees, create rules, and move budgeted money. Combined with SECURE_LOCAL_NET=true, anyone who can reach the port can do the same — the server warns loudly at startup when it detects that combination. Set ACTUAL_ENABLE_WRITES=false for a read-only deployment.

  • merge_payees cannot be undone. There are no delete tools at all.

  • DATA_DIR contains a plaintext SQLite copy of the budget. Treat it as sensitive; do not commit it (data/ is gitignored).

Development

npm run dev     # watch mode, .ts run directly by Node
npm run check   # biome + tsc
npm test        # vitest

See AGENTS.md for architecture and conventions.

Available Tools

34 tools
apply_rule_actionsApply rule actions to transactionsA
Destructive

Apply rule actions to specific transactions and SAVE the result. This is the write half of preview_rule_effects: preview first, then pass the transaction ids it returned. The actions are applied UNCONDITIONALLY to every id you pass — rule conditions are NOT evaluated here, so a wrong id is silently changed rather than skipped. Pass only ids you have actually seen, from preview_rule_effects or search_transactions; never ids you assembled yourself. Edits real transactions in bulk, at most 500 per call, and cannot be undone through this server. Actions use the same format as create_rule (see describe_rule_schema), and values are ids, not names — preview_rule_effects reports these as toId. Returns the ids actually updated, plus any that did not exist under missing.

Inputs: actions (required), transactionIds (required).

create_categoryCreate a categoryA

Create a budget category inside an existing category group. Get the group id from list_category_groups, or create the group first with create_category_group. Income categories behave differently from spending ones — set isIncome only for money coming in.

Inputs: name (required), groupId (required), hidden, isIncome.

create_category_groupCreate a category groupA

Create an empty category group to file categories under, then fill it with create_category. Groups are spending groups: Actual’s API cannot create an income group, and every budget already has the one it needs.

Inputs: name (required), hidden.

create_payeeCreate a payeeA

Create a payee by name and return it with its new id. Check resolve_name_to_id first — creating a payee that already exists under a slightly different name is how duplicates appear in the first place.

Inputs: name (required).

create_ruleCreate a ruleA

Create a rule from conditions and actions. Call describe_rule_schema first for the exact format. Conditions reference accounts, categories, and payees by id, not name. The rule applies to future imports and edits — it does not retroactively change existing transactions.

Inputs: actions (required), conditions (required), stage, conditionsOp.

describe_rule_schemaDescribe the rule formatA
Read-onlyIdempotent

Return the exact structure of an Actual rule: every condition field with the operators legal for it, the action operations, how values are typed, and worked examples. Call this BEFORE create_rule or update_rule — the condition format is a strict union and an invalid field/operator pairing is rejected.

Inputs: no named parameters.

find_duplicate_payeesFind likely duplicate payeesA
Read-onlyIdempotent

Group payees whose names differ only by case, punctuation, or a trailing store/reference number — Trader Joe’s #123 and TRADER JOES 456, for example. Each group names a suggestedTarget (the most-used member) and the other candidates, plus the reason they were grouped. Matching is exact once normalized, so an abbreviation and its expansion do NOT group: AMZN Mktp US*2H4 and Amazon are reported separately. An empty result therefore means "no name-shaped duplicates", not "no duplicates" — to find those, scan list_payees yourself and propose them to the user. The conservative rule is deliberate: a false positive here feeds an irreversible merge. This only suggests; nothing is merged. Confirm a group really is one merchant before calling merge_payees. Transfer payees are never included.

Inputs: minGroupSize.

get_budget_monthGet a month’s budgetA
Read-onlyIdempotent

Read one month’s budget: totals (income, budgeted, spent, balance, and toBudget — what is still unassigned) plus every category with its budgeted, spent, and balance amounts and its carryover flag. All amounts are integer cents; spending is negative. This is the tool for "am I over budget?". Income categories (isIncome: true) are different: Actual tracks money coming in as received, and leaves their budgeted/spent/balance at 0 on a standard envelope budget. Read received for those, and never report an income category as "0 spent" — the figure simply lives elsewhere.

Inputs: month (required).

get_noteGet a noteA
Read-onlyIdempotent

Read the note attached to an entity (transaction, account, category, …) by its id. Returns { note: null } when there is none.

Inputs: id (required).

get_transactionsGet an account’s transactionsA
Read-onlyIdempotent

List every transaction in one account between two dates, with no result cap. Use search_transactions for anything cross-account or filtered; this is the exhaustive per-account read, e.g. for reconciling. Split transactions are returned as the parent followed by each of its legs (isParent / isChild), so summing every row double-counts a split — total the legs, or the parents, not both.

Inputs: endDate (required), accountId (required), startDate (required).

hold_for_next_monthHold funds for next monthA
DestructiveIdempotent

Hold some of this month’s leftover "to budget" money back for next month, in integer cents. This ADDS to whatever is already held for that month — it does not replace it, so calling twice with 1000 leaves 2000 held. To correct a hold, call reset_budget_hold first. The amount is clamped to what is actually available, so the hold can be smaller than you asked for. Read heldAmount (how much the buffer really grew) and forNextMonth (the resulting total) rather than assuming the request landed in full; held: false means there was no surplus to hold at all.

Inputs: month (required), amount (required).

list_accountsList accounts and balancesA
Read-onlyIdempotent

List every account in the Actual Budget file with its current balance. Returns each account’s id, name, balance (in cents as amount and as a decimal in amountDecimal), whether it is off-budget (a tracking account), and whether it is closed — plus onBudgetTotal (open on-budget accounts) and total (all open accounts). The budget is synced with the server before reading. Balances are as of TODAY: a future-dated transaction, such as a posted schedule, is not counted, so these figures can be lower than the ones Actual’s own account screen shows. Mention that if a balance looks off rather than assuming the budget is wrong.

Inputs: no named parameters.

list_budget_monthsList budget monthsA
Read-onlyIdempotent

List every month the budget file covers, oldest first, as YYYY-MM. Use it to find the current or most recent month before reading or setting budget amounts.

Inputs: no named parameters.

list_categoriesList budget categoriesA
Read-onlyIdempotent

List every budget category with its id, name, and containing group. Categories are addressed by id by the budgeting and rule tools, so this is usually the first call when working with either. Hidden categories are excluded unless includeHidden is true.

Inputs: includeHidden.

list_category_groupsList category groupsA
Read-onlyIdempotent

List the groups categories are filed under, with their ids and how many categories each holds. Use this to find the groupId for create_category — list_categories only names groups that already have a visible category, so a new or empty group (categoryCount: 0) is only discoverable here.

Inputs: includeHidden.

list_payeesList payeesA
Read-onlyIdempotent

List every payee. With withUsage (the default) each payee also carries transactionCount and lastTransactionDate, which is what makes cleanup decisions possible — the busiest payee in a group is normally the one to merge others into. Payees with a transferAccountId represent the other side of a transfer, not a merchant, and must never be merged.

Inputs: withUsage.

list_rulesList rulesA
Read-onlyIdempotent

List the budget’s rules with their conditions and actions. Pass payeeId to list only the rules Actual associates with that payee, which is the quick way to see why transactions for one merchant keep getting a particular category.

Inputs: payeeId.

list_schedulesList scheduled transactionsA
Read-onlyIdempotent

List Actual’s scheduled (recurring) transactions with their next due date and amount. Useful context when a budget or rule looks wrong: a category may be funded for a schedule that has not posted yet.

Inputs: no named parameters.

list_tagsList tagsA
Read-onlyIdempotent

List the tags defined in this budget. Rules can match tags in transaction notes (hasTags), so this is the vocabulary available to such a rule.

Inputs: no named parameters.

merge_payeesMerge payeesA
Destructive

Merge one or more payees into a target payee: their transactions move to the target and the merged payees are removed. THIS CANNOT BE UNDONE — confirm the payees really are the same merchant before calling, and never merge a payee that has a transferAccountId, which would corrupt transfers. Takes ids, not names, so a near-miss on a name cannot silently merge the wrong thing.

Inputs: mergeIds (required), targetId (required).

preview_rule_effectsPreview what the rules would changeA
Read-onlyIdempotent

Run the budget’s rules over EXISTING transactions without saving anything, and report the field changes they would make. Actual applies rules on import and edit only, so transactions already in the budget are untouched until you act on them — this shows what a rule would have done to them. The usual flow is create_rule, then this to check it against real data, then apply_rule_actions to make the changes stick. IMPORTANT: this reports the net effect of the ENTIRE rule set, not one rule in isolation. Actual has no per-rule preview, and rules interact by rank, so a change shown here may come from a rule other than the one you just wrote. Verify against list_rules before assuming which rule caused it. Each change gives from/to as readable names plus fromId/toId for the fields that hold ids — pass toId as the action value to apply_rule_actions. Transactions the rules would not change are omitted, so an empty entries with a non-zero scanned means the rules are a no-op here.

Inputs: limit, dateTo, offset, payeeId, +6 more.

reset_budget_holdRelease a held amountA
DestructiveIdempotent

Release everything held back for next month, returning it to this month’s "to budget". Safe to call when nothing is held. Returns the resulting forNextMonth, which should be 0.

Inputs: month (required).

resolve_name_to_idResolve a name to an idA
Read-onlyIdempotent

Look up the id of an account, category, payee, or schedule by its exact name. Returns { id: null } when nothing matches — that is a normal answer, not an error, so use it to check whether something exists before creating it. Most other tools take ids, so this saves listing everything just to find one.

Inputs: name (required), type (required).

run_bank_syncFetch transactions from linked banksA
Destructive

Trigger Actual’s bank sync to pull new transactions from linked accounts, optionally for one account. Slow and rate-limited by the bank, so call it deliberately rather than before every read. Fails rather than reporting a hollow success when the account does not exist, is closed, or has no bank link. Returns the accounts it actually synced — Actual does not report how many transactions arrived, so follow up with search_transactions rather than claiming a count.

Inputs: accountId.

search_transactionsSearch transactionsA
Read-onlyIdempotent

Search transactions across every account, filtered by any combination of date range, account, payee, category, note text, payee-name text, amount range, and cleared/reconciled state. Amounts are integer cents and negative means an outflow. Results are newest-first and capped by limit (default 100, max 1000); when truncated is true, more matched than were returned — page with offset or narrow the filters rather than assuming you have seen everything. This is the tool for payee cleanup: it can answer "where else does this payee appear?", which the per-account listing cannot.

Inputs: limit, dateTo, offset, cleared, +10 more.

set_budget_amountSet a category’s budgetA
DestructiveIdempotent

Set the amount budgeted to one category for one month, in integer cents. This replaces the existing amount rather than adding to it. Returns the category’s resulting budgeted/spent/balance figures so the effect is visible immediately.

Inputs: month (required), amount (required), categoryId (required).

set_budget_carryoverSet a category’s carryoverA
DestructiveIdempotent

Turn rollover on or off for a category. With carryover on, an unspent balance rolls into the next month instead of returning to "to budget"; an overspend carries forward as a negative. IMPORTANT: this is not scoped to the one month. Actual applies the flag from the given month FORWARD to the end of the budget range, overwriting it on every later month — including ones set deliberately. The result reports only the month you named, so say what you changed rather than implying it was one month.

Inputs: month (required), carryover (required), categoryId (required).

sync_budgetSync with the Actual serverA
Read-onlyIdempotent

Pull the latest changes from the Actual sync server. Read tools already sync where it matters, so reach for this after editing the budget in the Actual UI and wanting those edits reflected immediately.

Inputs: no named parameters.

update_categoryUpdate a categoryA
DestructiveIdempotent

Rename a category, move it to another group, or hide/unhide it. Only the fields you pass are changed. Hiding keeps history intact and is the safe alternative to deleting a category you no longer use.

Inputs: id (required), name, hidden, groupId.

update_category_groupUpdate a category groupA
DestructiveIdempotent

Rename a category group or hide/unhide it. Only the fields you pass are changed. Hiding a group hides every category in it, so list_categories will report those categories as hidden — unhide the group here rather than trying to unhide them one by one.

Inputs: id (required), name, hidden.

update_noteSet a noteA
DestructiveIdempotent

Replace the note attached to an entity by its id. Notes are free text and overwrite wholesale — read the existing note first with get_note if you mean to append to it.

Inputs: id (required), note (required).

update_payeeRename a payeeA
DestructiveIdempotent

Rename a payee. Renaming is the only edit Actual’s public API exposes for payees — favorite and category-learning flags are not reachable. Renaming does not merge: to combine two payees, use merge_payees.

Inputs: id (required), name (required).

update_ruleUpdate a ruleA
DestructiveIdempotent

Replace a rule’s conditions and actions. This overwrites the whole rule, so send the complete set — anything omitted is dropped, not preserved. Read the current rule with list_rules first.

Inputs: id (required), actions (required), conditions (required), stage, +1 more.

update_transactionUpdate a transactionA
DestructiveIdempotent

Change a transaction’s category, payee, notes, cleared flag, date, or amount. Only the fields you pass are touched; pass null to clear a category, payee, or note. Amounts are integer cents. Returns the transaction as stored afterwards — rules may rewrite a value on write, so trust the response over the request. The main tool for recategorizing during cleanup.

Inputs: id (required), date, notes, amount, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 34 tools

    Disambiguation4/5

    Most tools target a clearly distinct entity and action, and the descriptions explicitly separate similar-looking reads like get_transactions vs search_transactions and preview_rule_effects vs apply_rule_actions. A few pairs such as set_budget_amount vs set_budget_carryover require reading the description, but misselection is unlikely.

    Naming Consistency5/5

    All names use snake_case with a predictable verb_noun pattern: list_, get_, create_, update_, set_, merge_, find_, preview_, apply_, reset_. Even the slightly longer names like hold_for_next_month remain consistent and readable.

    Tool Count3/5

    34 tools is heavy for an MCP server, well above the typical 3-15 range. The domain is broad enough that each tool maps to a distinct operation, but the surface could likely be trimmed with more generic resource patterns.

    Completeness4/5

    Core workflows across accounts, transactions, payees, rules, categories, category groups, budget months, notes, and sync are well covered. Gaps remain around lifecycle operations such as deleting rules or transactions, creating transactions, and writing accounts/schedules, though hide/merge/update workarounds cover many cases.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      MCP server for integrating Actual Budget with Claude and other LLM assistants.
      17
      494 npm
      287
      TypeScript
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Read-only MCP server for YNAB that provides tools for budgets, accounts, categories, transactions, and financial summaries via HTTP or stdio.
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A Model Context Protocol server for YNAB (You Need A Budget). Enables users to query budgets, accounts, categories, transactions, and more, as well as create, update, and delete transactions and manage scheduled transactions from any MCP client.
      27
      30 PyPI
      2
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      A lightweight MCP server for managing personal finances locally. It allows users to log transactions, view summaries, manage categories, and interact with their budget via any MCP-compatible LLM client.
      12
      -