Actual Budget — Claude Code MCP server: features and setup
Connects Actual Budget to an MCP client for budget analysis, transaction changes, and category management. Useful when you want to work with finances in chat.
claude mcp add actual-budget-mcp -e ACTUAL_SERVER_URL=<ACTUAL_SERVER_URL> -e ACTUAL_PASSWORD=<ACTUAL_PASSWORD> -e ACTUAL_SESSION_TOKEN=<ACTUAL_SESSION_TOKEN> -e ACTUAL_BUDGET_ID=<ACTUAL_BUDGET_ID> -e ACTUAL_ENCRYPTION_PASSWORD=<ACTUAL_ENCRYPTION_PASSWORD> -- npx -y actual-budget-mcpWhat Actual Budget does
This MCP server links Actual Budget with Claude Code and other MCP clients. It can answer questions about spending, produce projections, compare planned and actual amounts, and summarize a month. It also lets the model add or edit transactions and transfers, plus manage categories, payees, and rules.
Names can be used instead of IDs, with suggestions when a name is unclear. Delete operations show a preview and wait for confirmation, while ACTUAL_READ_ONLY=1 removes write tools from the model. The server handles split and residual amounts across currencies and includes repair_sync for rebuilding local sync state. A running Actual Budget server is required; the Claude Code setup also needs Node.js 22.14 or newer.
What it helps with
- find where money went during a month
- compare a budget with actual spending
- add an expense or transfer from chat
- change categories, payees, or rules
- rebuild the local sync state
Example prompts for the agent
- Check how much I spent on food this month and compare it with the budget.
- Add this expense to Actual Budget, then check for a duplicate.
- List my budget categories and rules, and explain which ones apply to this transaction.
How to install Actual Budget
Platform CLI
claude mcp add actual-budget-mcp -e ACTUAL_SERVER_URL=<ACTUAL_SERVER_URL> -e ACTUAL_PASSWORD=<ACTUAL_PASSWORD> -e ACTUAL_SESSION_TOKEN=<ACTUAL_SESSION_TOKEN> -e ACTUAL_BUDGET_ID=<ACTUAL_BUDGET_ID> -e ACTUAL_ENCRYPTION_PASSWORD=<ACTUAL_ENCRYPTION_PASSWORD> -- npx -y actual-budget-mcpReplace <…> with your own values. 4 more environment variables are in the server README
Platform CLI
codex mcp add actual-budget --env ACTUAL_SERVER_URL=<ACTUAL_SERVER_URL> --env ACTUAL_PASSWORD=<ACTUAL_PASSWORD> --env ACTUAL_SESSION_TOKEN=<ACTUAL_SESSION_TOKEN> --env ACTUAL_BUDGET_ID=<ACTUAL_BUDGET_ID> --env ACTUAL_ENCRYPTION_PASSWORD=<ACTUAL_ENCRYPTION_PASSWORD> -- npx -y actual-budget-mcpReplace <…> with your own values. 4 more environment variables are in the server README
Config file
{
"mcpServers": {
"actual-budget": {
"command": "npx",
"args": [
"-y",
"actual-budget-mcp"
],
"env": {
"ACTUAL_SERVER_URL": "<ACTUAL_SERVER_URL>",
"ACTUAL_PASSWORD": "<ACTUAL_PASSWORD>",
"ACTUAL_SESSION_TOKEN": "<ACTUAL_SESSION_TOKEN>",
"ACTUAL_BUDGET_ID": "<ACTUAL_BUDGET_ID>",
"ACTUAL_ENCRYPTION_PASSWORD": "<ACTUAL_ENCRYPTION_PASSWORD>"
}
}
}
}Replace <…> with your own values. 4 more environment variables are in the server README
Config file
{
"servers": {
"actual-budget": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"actual-budget-mcp"
],
"env": {
"ACTUAL_SERVER_URL": "<ACTUAL_SERVER_URL>",
"ACTUAL_PASSWORD": "<ACTUAL_PASSWORD>",
"ACTUAL_SESSION_TOKEN": "<ACTUAL_SESSION_TOKEN>",
"ACTUAL_BUDGET_ID": "<ACTUAL_BUDGET_ID>",
"ACTUAL_ENCRYPTION_PASSWORD": "<ACTUAL_ENCRYPTION_PASSWORD>"
}
}
}
}Replace <…> with your own values. 4 more environment variables are in the server README
Platform CLI
gemini mcp add -e ACTUAL_SERVER_URL=<ACTUAL_SERVER_URL> -e ACTUAL_PASSWORD=<ACTUAL_PASSWORD> -e ACTUAL_SESSION_TOKEN=<ACTUAL_SESSION_TOKEN> -e ACTUAL_BUDGET_ID=<ACTUAL_BUDGET_ID> -e ACTUAL_ENCRYPTION_PASSWORD=<ACTUAL_ENCRYPTION_PASSWORD> actual-budget npx -y actual-budget-mcpReplace <…> with your own values. 4 more environment variables are 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
How do I install Actual Budget in Claude Code?
Run `claude mcp add actual-budget-mcp -e ACTUAL_SERVER_URL=<ACTUAL_SERVER_URL> -e ACTUAL_PASSWORD=<ACTUAL_PASSWORD> -e ACTUAL_SESSION_TOKEN=<ACTUAL_SESSION_TOKEN> -e ACTUAL_BUDGET_ID=<ACTUAL_BUDGET_ID> -e ACTUAL_ENCRYPTION_PASSWORD=<ACTUAL_ENCRYPTION_PASSWORD> -- npx -y actual-budget-mcp`.
What does Actual Budget do?
It connects an Actual Budget server to an MCP client, answers questions about spending, and supports changes to transactions, categories, payees, and rules.
What does Claude Code need to use it?
You need a running Actual Budget server plus its URL, password, session token, budget ID, and encryption password. This setup also requires Node.js 22.14 or newer.
