Actual Budget MCP Server — Claude Code MCP server for budgets
Gives an AI assistant access to your Actual Budget data: accounts, transactions, categories and reports, all through plain-language requests.
claude mcp add --env ACTUAL_SERVER_URL=<ACTUAL_SERVER_URL> --env ACTUAL_PASSWORD=<ACTUAL_PASSWORD> --env ACTUAL_BUDGET_SYNC_ID=<ACTUAL_BUDGET_SYNC_ID> --env ACTUAL_DATA_DIR=<ACTUAL_DATA_DIR> --env ACTUAL_BUDGET_ENCRYPTION_PASSWORD=<ACTUAL_BUDGET_ENCRYPTION_PASSWORD> --transport stdio actual-budget-mcp-server -- npx -y actual-mcpWhat Actual Budget MCP Server does
The server hands your assistant the contents of an Actual Budget file: accounts with balances, transaction history, categories, payees and rules. A second group of tools covers analytics — spending by category, monthly income and expenses, budget versus actual, net worth over time, cash flow per month or week. Five of those tools answer in JSON instead of markdown so the figures stay machine-readable: amounts come as whole cents, and each reply includes an amountsIn field that spells out the sign conventions.
Saved custom reports and dashboards are editable too: create, update and delete reports, add widgets to a page, move and resize them, rename or remove pages. Two prompts ship with it, financial-insights and budget-review. You need Node.js v16 or higher and a configured Actual Budget instance; Docker Desktop is optional. Local setup is git clone, then npm install and npm run build.
Configuration lives in environment variables: ACTUAL_DATA_DIR for the data folder, ACTUAL_SERVER_URL and ACTUAL_PASSWORD for a remote server, ACTUAL_BUDGET_SYNC_ID to pick a budget. When the server enforces OpenID login with ACTUAL_OPENID_ENFORCE=true, password auth is off, so ACTUAL_PASSWORD is useless there — supply ACTUAL_SESSION_TOKEN instead, which takes precedence. That token grants full access to your budgets, so treat it like a password. An expired or wrong token does not stop the server from starting; tool calls then fail with an authentication error.
What it helps with
- check balances across every account at once
- filter transactions by date, amount or payee
- compare budgeted amounts with what was actually spent
- break down spending by category for a month
- lay out dashboard widgets and rearrange them
Example prompts for the agent
- Show me the balances on all my Actual Budget accounts
- Compare budgeted and actual spending by category last month
- Add a spending-by-category widget to my dashboard page
How to install Actual Budget MCP Server
Platform CLI
claude mcp add --env ACTUAL_SERVER_URL=<ACTUAL_SERVER_URL> --env ACTUAL_PASSWORD=<ACTUAL_PASSWORD> --env ACTUAL_BUDGET_SYNC_ID=<ACTUAL_BUDGET_SYNC_ID> --env ACTUAL_DATA_DIR=<ACTUAL_DATA_DIR> --env ACTUAL_BUDGET_ENCRYPTION_PASSWORD=<ACTUAL_BUDGET_ENCRYPTION_PASSWORD> --transport stdio actual-budget-mcp-server -- npx -y actual-mcpReplace <…> with your own values. 1 more environment variable is in the server README
Platform CLI
codex mcp add actual-budget-mcp-server --env ACTUAL_SERVER_URL=<ACTUAL_SERVER_URL> --env ACTUAL_PASSWORD=<ACTUAL_PASSWORD> --env ACTUAL_BUDGET_SYNC_ID=<ACTUAL_BUDGET_SYNC_ID> --env ACTUAL_DATA_DIR=<ACTUAL_DATA_DIR> --env ACTUAL_BUDGET_ENCRYPTION_PASSWORD=<ACTUAL_BUDGET_ENCRYPTION_PASSWORD> -- npx -y actual-mcpReplace <…> with your own values. 1 more environment variable is in the server README
Config file
{
"mcpServers": {
"actual-budget-mcp-server": {
"command": "npx",
"args": [
"-y",
"actual-mcp"
],
"env": {
"ACTUAL_SERVER_URL": "<ACTUAL_SERVER_URL>",
"ACTUAL_PASSWORD": "<ACTUAL_PASSWORD>",
"ACTUAL_BUDGET_SYNC_ID": "<ACTUAL_BUDGET_SYNC_ID>",
"ACTUAL_DATA_DIR": "<ACTUAL_DATA_DIR>",
"ACTUAL_BUDGET_ENCRYPTION_PASSWORD": "<ACTUAL_BUDGET_ENCRYPTION_PASSWORD>"
}
}
}
}Replace <…> with your own values. 1 more environment variable is in the server README
Config file
{
"servers": {
"actual-budget-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"actual-mcp"
],
"env": {
"ACTUAL_SERVER_URL": "<ACTUAL_SERVER_URL>",
"ACTUAL_PASSWORD": "<ACTUAL_PASSWORD>",
"ACTUAL_BUDGET_SYNC_ID": "<ACTUAL_BUDGET_SYNC_ID>",
"ACTUAL_DATA_DIR": "<ACTUAL_DATA_DIR>",
"ACTUAL_BUDGET_ENCRYPTION_PASSWORD": "<ACTUAL_BUDGET_ENCRYPTION_PASSWORD>"
}
}
}
}Replace <…> with your own values. 1 more environment variable is in the server README
Platform CLI
gemini mcp add -e ACTUAL_SERVER_URL=<ACTUAL_SERVER_URL> -e ACTUAL_PASSWORD=<ACTUAL_PASSWORD> -e ACTUAL_BUDGET_SYNC_ID=<ACTUAL_BUDGET_SYNC_ID> -e ACTUAL_DATA_DIR=<ACTUAL_DATA_DIR> -e ACTUAL_BUDGET_ENCRYPTION_PASSWORD=<ACTUAL_BUDGET_ENCRYPTION_PASSWORD> actual-budget-mcp-server npx -y actual-mcpReplace <…> with your own values. 1 more environment variable is in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Actual Budget MCP Server
How do I install Actual Budget MCP Server in Claude Code?
Run `claude mcp add actual-mcp -e ACTUAL_SERVER_URL=<ACTUAL_SERVER_URL> -e ACTUAL_PASSWORD=<ACTUAL_PASSWORD> -e ACTUAL_BUDGET_SYNC_ID=<ACTUAL_BUDGET_SYNC_ID> -e ACTUAL_BUDGET_ENCRYPTION_PASSWORD=<ACTUAL_BUDGET_ENCRYPTION_PASSWORD> -- npx -y actual-mcp`.
What does Actual Budget MCP Server do?
It exposes accounts, transactions, categories, payees and rules from Actual Budget to an LLM assistant, along with analytics such as spending by category, monthly summaries, net worth and cash flow.
What do I need before running it?
Node.js v16 or higher and a working Actual Budget setup. For a remote server set ACTUAL_SERVER_URL and ACTUAL_PASSWORD; with OpenID login you pass ACTUAL_SESSION_TOKEN instead of a password.
