Atlas / MCP servers / agigante80 / actual-mcp-server

actual-mcp-serverBLOCK

Name: actual-mcp-server
Author: agigante80

mcp/agigante80/actual-mcp-server

MCP server by agigante80 · actual budget · ai assistant · api server · Audited 2026-10-12

Talk to your self-hosted Actual Budget from any MCP client: a remote HTTP server for LibreChat/LobeChat or a local stdio process for Claude Desktop, with 71 tools for transactions, budgets, rules, and bank sync. No Docker needed for local use.

Verdict

BLOCK

Grade

Trust score

68 /100

Exposed tools

85 46r · 28w · 11d

Transport

stdio · streamable-http

License

MIT

Stars

Overview

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

Actual MCP Server

[](https://www.npmjs.com/package/actual-mcp-server) [](https://www.npmjs.com/package/actual-mcp-server) [](https://opensource.org/licenses/MIT) [](https://nodejs.org/) [](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io/) [](https://hub.docker.com/r/agigante80/actual-mcp-server) [](https://hub.docker.com/r/agigante80/actual-mcp-server) [](https://ca.unraid.net/apps/actual-mcp-server-0bghkvs0c7c8bg) [](https://github.com/agigante80/actual-mcp-server/actions) [](https://github.com/agigante80/actual-mcp-server)

Talk to your budget. Run it anywhere. Trust it in production.

Actual MCP Server is a Model Context Protocol server that connects any MCP-compatible AI assistant (such as LibreChat, LobeChat, Claude Desktop, and more) directly to your self-hosted [Actual Budget](https://actualbudget.or

Read from source at commit 582fab680352OBSERVED · 2026-10-12

Connect

Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.

claude-code

claude mcp add actual-mcp-server --env ACTUAL_BUDGET_PASSWORD=${ACTUAL_BUDGET_PASSWORD} --env ACTUAL_PASSWORD=${ACTUAL_PASSWORD} --env AUTH_BUDGET_ACL_SOURCE=${AUTH_BUDGET_ACL_SOURCE} --env AUTH_PROVIDER=${AUTH_PROVIDER} -- npx -y [email protected]

claude-desktop

{
  "mcpServers": {
    "actual-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]"
      ],
      "env": {
        "ACTUAL_BUDGET_PASSWORD": "${ACTUAL_BUDGET_PASSWORD}",
        "ACTUAL_PASSWORD": "${ACTUAL_PASSWORD}",
        "AUTH_BUDGET_ACL_SOURCE": "${AUTH_BUDGET_ACL_SOURCE}",
        "AUTH_PROVIDER": "${AUTH_PROVIDER}"
      }
    }
  }
}

Exposed tools (85)

46 read · 28 write · 11 destructive. Blast radius: 11 tools can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.

Tool	Risk	Description
`actual-mcp-server`	read	MCP server for Actual Budget
`actual_account_groups_create`	write	Create a custom account group for organising accounts in the sidebar.
`actual_account_groups_delete`	destructive	Delete a custom account group. The accounts in it are NOT deleted: they become ungrouped.
`actual_account_groups_list`	read	List the custom account groups used to organise accounts in the sidebar.
`actual_account_groups_update`	write	Rename a custom account group or change its sidebar position.
`actual_accounts_close`	read	Mark an account as closed in Actual Budget. Closed accounts are hidden from most views.
`actual_accounts_create`	write	Create a new account in Actual Budget
`actual_accounts_delete`	destructive	Delete an account from Actual Budget. DESTRUCTIVE: if the account has transactions, they are
`actual_accounts_get_balance`	read	Get the current balance of a specific account. Required: - id: Account UUID Optional: - cutoff: Date to calculate balance up to (YYYY-MM-DD format) Returns the account balance as a number (in cents), or an error if the account does not exist. Example: {
`actual_accounts_list`	read	List all accounts in Actual Budget including checking, savings, credit cards, and investment accounts. Returns account ID, name, balance (in cents), on-budget/off-budget status, and open/closed state.
`actual_accounts_reopen`	read	Reopen a previously closed account in Actual Budget. The account becomes active again and
`actual_accounts_update`	write	Update an account
`actual_budgets_export`	read	Export the currently active budget as an Actual Budget
`actual_budgets_getMonth`	read	Get budget data for a specific month in YYYY-MM format (e.g.,
`actual_budgets_getMonths`	read	Get a list of all available budget months with summary data. Returns an array of months showing total budgeted, spent, and income for each month. Useful for viewing budget history and trends over time.
`actual_budgets_get_all`	read	Get a list of all available budget files. Useful for multi-budget management and discovering available budgets on the server.
`actual_budgets_holdForNextMonth`	read	Hold an amount from this month
`actual_budgets_import`	write	Restore or import a budget from an Actual Budget
`actual_budgets_list_available`	read	List all pre-configured budgets available for switching.
`actual_budgets_resetHold`	destructive	Reset the budget hold for a month, releasing any amount previously held for next month via holdBudgetForNextMonth.
`actual_budgets_setAmount`	write	Set the budgeted amount for a specific category in a given month. Amount in cents
`actual_budgets_setCarryover`	write	Set carryover behavior for a category in a specific month. When enabled (true), leftover budget or overspending automatically rolls into the next month
`actual_budgets_switch`	read	Switch to a different pre-configured budget for all subsequent operations in this session.
`actual_budgets_transfer`	write	Transfer budget amount between categories. Decreases the source category budget and increases the target category budget by the specified amount for the given month.
`actual_categories_create`	write	Create a category. REQUIRED: group_id (category group UUID). Use actual_category_groups_get to find available groups. Optional: is_income (boolean, defaults to false for expense categories).
`actual_categories_delete`	destructive	Delete a category from Actual Budget. Transactions using this category will need to be recategorized. This operation cannot be undone.
`actual_categories_get`	read	List all budget categories organized by category groups. Categories are spending/income buckets (e.g., Groceries, Rent, Salary) used for budgeting and transaction categorization. Returns both grouped view and flat list with category IDs, names, and group assignments.
`actual_categories_update`	write	Update an existing category in Actual Budget. You can rename the category, move it to a different group, or change its properties.
`actual_category_groups_create`	write	Create a new category group in Actual Budget. Category groups help organize categories into logical sections (e.g.,
`actual_category_groups_delete`	destructive	Delete a category group from Actual Budget. Note: Categories within the group will be moved to a default group or ungrouped. This operation cannot be undone.
`actual_category_groups_get`	read	List all category groups in Actual Budget. Category groups organize related categories together (e.g.,
`actual_category_groups_update`	write	Update an existing category group in Actual Budget. You can rename the group, change whether it
`actual_entities_search`	read	Find accounts, categories, or payees by a name pattern. Use this to resolve a partial or mistyped name to its entity (the fix for
`actual_get_context`	read	Read the budget structure and entity UUIDs (accounts, category groups with nested categories, and payees) in a single call.
`actual_get_id_by_name`	read	Resolve an entity name to its UUID. Looks up the UUID for any Account, Payee, Category, or Schedule by their display name. This is useful when you know the human-readable name but need the ID for other API calls. Allowed types:
`actual_notes_get`	read	Get the note attached to an entity in Actual Budget.
`actual_notes_update`	destructive	Set or clear the note attached to an entity in Actual Budget.
`actual_payee_rules_get`	read	Get all payee rules associated with a specific payee. Returns PayeeRule objects that show how transactions with this payee are automatically processed (conditions and actions).
`actual_payees_common_list`	read	Return the most frequently used payees from recent transaction history (last ~12 weeks, top 10,
`actual_payees_create`	write	Create a new payee in Actual Budget
`actual_payees_delete`	destructive	Delete a payee from Actual Budget. Transactions using this payee will have it removed. This
`actual_payees_get`	read	List all payees in Actual Budget. Payees represent merchants, service providers, individuals, or other entities you transact with. Returns payee ID, name, and optional transfer account information for internal transfers.
`actual_payees_merge`	write	Merge one or more payees into a target payee. This consolidates duplicate payees by merging
`actual_preferences_get`	read	Read the budget\
`actual_query_run`	write	Run a read-only SQL query against the budget data. Prefer SQL; a bare table name (e.g.
`actual_rules_create`	write	Create a budget rule. ${CONDITION_OPERATORS_HELP} Stage: omit it for the normal stage (recommended), or
`actual_rules_create_or_update`	write	Create a rule, or update the existing rule with the same conditions. Prevents duplicates. A rule matches when it has the same conditions (field, op, value) and conditionsOp, in any order. On a match the rule
`actual_rules_delete`	destructive	Delete a budget rule from Actual Budget. The rule will no longer be applied to new or
`actual_rules_get`	read	List all budget rules in Actual Budget. Rules automate transaction categorization and other budget operations based on conditions. Each rule has conditions (e.g., payee matches
`actual_rules_update`	write	Update an existing budget rule by ID. Only provide the fields you want to change; do not repeat the rule ID inside fields. ${CONDITION_OPERATORS_HELP} Stage: omit it to leave the rule where it is, pass null for the normal stage, or
`actual_schedules_create`	write	Create a schedule, one-off (YYYY-MM-DD date) or recurring (RecurConfig object: frequency and start, optional endMode, monthly patterns such as the last day or the second Monday). Amounts are in cents, negative for expenses.
`actual_schedules_delete`	destructive	Permanently delete a schedule from Actual Budget. The schedule
`actual_schedules_get`	read	List all schedules in Actual Budget. Schedules automate recurring transactions (e.g. monthly rent, weekly grocery runs). Each schedule has a date rule (one-off or RecurConfig), optional payee/account/amount, and a next_date field showing when it fires next.
`actual_schedules_update`	write	Update a schedule; supply only the fields to change. A new date replaces the stored recurrence, patterns included. Set resetNextDate: true when changing the date or recurrence.
`actual_server_get_version`	read	Get the version of the Actual Budget server. Returns the version string of the connected Actual Budget server instance. This is the self-hosted Actual Budget server version, not the MCP server version. Use
`actual_server_info`	read	Get MCP server version and system information. Returns: - Server version - Server name - Node.js version - MCP SDK version - Actual Budget API version - Total tools available - Uptime Use this to check server status, verify version compatibility, or debug issues.
`actual_session_close`	read	Close one of your idle MCP sessions to free up connection slots. Useful when you get
`actual_session_list`	read	List your active MCP sessions with their activity status. Useful for diagnosing connection issues or seeing which sessions can be closed. The pool totals cover every session; the list shows only sessions you opened.
`actual_tags_create`	write	Create a new tag in Actual Budget. The
`actual_tags_delete`	destructive	Delete a tag from Actual Budget by its UUID.
`actual_tags_list`	read	List all tags defined in Actual Budget. Tags are stored without a leading
`actual_tags_update`	write	Update an existing tag in Actual Budget. At least one of tag/color/description must be provided.
`actual_test_bad`	read	b
`actual_test_do`	read	Do a thing
`actual_test_meta`	read	m
`actual_test_opt`	read	o
`actual_test_sum`	read	sum
`actual_test_throw`	read	t
`actual_transactions_create`	write	Create a new transaction in Actual Budget. Amount should be in cents (negative for expenses, positive for income).
`actual_transactions_delete`	destructive	Delete a transaction from Actual Budget by its ID.
`actual_transactions_filter`	read	Get transactions with advanced filtering. Supports filtering by amount range, category, payee, notes, and status. Returns filtered transactions matching all specified criteria.
`actual_transactions_get`	read	Get all transactions for a specific account within a date range. Returns transaction details including date, amount (cents), payee, category, notes, and cleared status. Dates in YYYY-MM-DD format. Perfect for account reconciliation and spending analysis.
`actual_transactions_import`	write	Bulk import transactions with automatic reconciliation and duplicate detection. Matches against existing transactions using imported_id to prevent duplicates. Ideal for importing bank statements, CSV files, or syncing from external sources. Automatically applies budget rules.
`actual_transactions_merge`	write	Merge two transactions (e.g. a bank-imported duplicate and a manual entry). Same account and same amount required; split children cannot be merged.
`actual_transactions_search_by_category`	read	Search transactions by category name. Returns all transactions in a specific category with optional date range, account, and amount filters. Perfect for analyzing spending in budget categories.
`actual_transactions_search_by_month`	read	Search transactions for a specific month. Returns all transactions matching the month and optional filters (account, category, payee, amount range). Efficiently queries by date range.
`actual_transactions_search_by_payee`	read	Search transactions by payee name. Returns all transactions for a specific payee with optional date range, category, and amount filters. Useful for analyzing spending patterns with specific vendors or service providers.
`actual_transactions_summary_by_category`	read	Get spending summary grouped by category using ActualQL aggregation. Returns total amount and transaction count per category for a date range. Perfect for budget analysis and expense tracking. By default excludes income categories (set includeIncome=true to include them).
`actual_transactions_summary_by_payee`	read	Get spending summary grouped by payee using ActualQL aggregation. Returns total amount and transaction count per payee for a date range. Useful for identifying top vendors and analyzing merchant spending patterns. Results are ordered by total amount (highest first).
`actual_transactions_update`	write	Update an existing transaction in Actual Budget. Provide the transaction ID and the fields you want to update.
`actual_transfers_create`	write	Create a paired transfer between two accounts — a debit on the source account and a credit
`math.add`	write	Add two numbers
`search.docs`	read	Search a small demo document store
`showLargeTransactions`	read	Show recent transactions over a specified amount
`test`	read	test

Trust audit

BLOCKgrade D · trust 68/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.

Layer	What it checks	Result
L0	Provenance & inventory	WARN
L1	Static analysis of the code	FAIL
L2	Instruction surface (what it tells the agent)	PASS
L3	Class-specific surface	WARN
L4	Behavioural (sandbox)	SKIPPED

What the source does

Filesystem: declared (7 observation(s))
Network: declared (9 observation(s))
Shell: declared (1 observation(s))
Dependencies: not all pinned
Secrets in source: found

Findings (25)

HIGHNetwork egress · net.tls_off · CWE-200, CWE-319

scripts/diag-270-http.mjs:21

process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'; // local self-signed bearer cert on :3601

Why it matters. certificate verification is disabled

Fix. leave verification on

MEDIUMInventory / provenance · inv.binary · CWE-1104

test-data/2026-01-08-Test Budget.zip

2026-01-08-Test Budget.zip

Why it matters. a compiled or binary member cannot be reviewed from source

Fix. ship source, or explain the binary in the README

MEDIUMInformation disclosure · disclose.log_secret · CWE-209, CWE-532

src/server/httpServer.ts:923

logger.info(`🔒 OIDC authentication enabled (JWT Bearer token required; issuer: ${config.OIDC_ISSUER})`);

MEDIUMInformation disclosure · disclose.log_secret · CWE-209, CWE-532

src/server/httpServer.ts:932

logger.info(`🔒 HTTP authentication enabled (static Bearer token required)`);

MEDIUMNetwork egress · net.raw_ip · CWE-200, CWE-319

docker-compose.yaml:45

#   http://192.168.1.50:5006       - Actual Budget on another machine on your network

MEDIUMNetwork egress · net.raw_ip · CWE-200, CWE-319

docker-compose.yaml:142

# Examples: http://localhost:5006, http://192.168.1.50:5006, https://actual.yourdomain.com

MEDIUMHard-coded secrets · secret.generic · CWE-798, CWE-321

tests/unit/budget_acl_enforcement.test.js:466

password: 'pwd-secret-DO-NOT-LEAK',

MEDIUMHard-coded secrets · secret.generic · CWE-798, CWE-321

tests/unit/zod_error_format.test.js:107

const secret = 'SUPER_SECRET_VALUE_12345';

MEDIUMFilesystem / path · mcp.destructive_tools · CWE-22, CWE-59

actual_account_groups_delete, actual_accounts_delete, actual_budgets_resetHold, actual_categories_delete, actual_category_groups_delete, actual_notes_update, actual_payees_delete, actual_rules_delete,

Why it matters. 11 tool(s) can delete or overwrite

Fix. prefer a read-only mode or scoped tokens; the page states the blast radius

LOWInventory / provenance · inv.binary · CWE-1104

tests/unit/budgets_export.test.js

budgets_export.test.js

Why it matters. a compiled or binary member cannot be reviewed from source

Fix. ship source, or explain the binary in the README

LOWInventory / provenance · inv.hidden_file · CWE-1104

.leak-guard-allow

.leak-guard-allow

Why it matters. hidden member outside the usual dotfiles

Fix. review its purpose

LOWInformation disclosure · disclose.log_secret · CWE-209, CWE-532

tests/unit/logger_redaction.test.js:101

logger.info('inbound', { headers: { authorization: 'Bearer abc.def' }, password: 'topsecretpw', note: 'LIVE-SECRET-TOKEN-XYZ123 here', accountId: 'a1' });

LOWInformation disclosure · disclose.log_secret · CWE-209, CWE-532

tests/unit/oidc_token_source.test.js:107

console.log(`\n[oidc-token-source] Results: ${passed} passed, ${failed} failed`);