Actual Budget
Connect Claude to your Actual Budget server for analysis, edits and previewed deletes
- Pricing
- Open source
- Platforms
- CLI, self-hosted, macOS
- Runs
- Locally
- Version
- 0.12.0
- Listing updated
- 3 days ago
About Actual Budget
Actual Budget is an open-source MCP server for finance and payments. It runs locally on your machine and is started by your AI client.
This server connects an MCP client to your own Actual Budget instance, which can be local or remote. It offers 44 tools for reading accounts, budgets, transactions, categories, payees, rules and schedules, for analysis such as projections, category trends, budget vs actual and spending breakdowns, and for writes such as creating, splitting, transferring and recategorising transactions or moving budget amounts.
Care around changes is its theme. Every delete previews what it will remove and waits for confirmation, new transactions are checked for duplicates, and setting ACTUAL_READ_ONLY=1 hides all write tools from the model. A repair_sync tool rebuilds local sync state when the Actual API and your server disagree. Names can be used instead of IDs, dates like last month or hace 3 meses are understood in English and Spanish, and multi-currency splits are reconciled.
On Claude Desktop it installs as a drag-and-drop extension that needs no separate Node; other clients use npx with a server URL, password or session token, and the budget Sync ID. The README says data stays on your machine except for what goes to whichever model your client uses. A chat toolset of 18 everyday tools trims the tool descriptions, and an HTTP mode serves read and write paths with separate tokens. ChatGPT is not supported because its connectors need OAuth.
Install
Run in a terminal
claude mcp add actual-budget-mcp --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>' --env ACTUAL_ENCRYPTION_PASSWORDS='<ACTUAL_ENCRYPTION_PASSWORDS>' --env ACTUAL_HTTP_TOKEN='<ACTUAL_HTTP_TOKEN>' --env ACTUAL_HTTP_WRITE_TOKEN='<ACTUAL_HTTP_WRITE_TOKEN>' -- npx -y actual-budget-mcpAdd to claude_desktop_config.json
{
"mcpServers": {
"actual-budget-mcp": {
"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>",
"ACTUAL_ENCRYPTION_PASSWORDS": "<ACTUAL_ENCRYPTION_PASSWORDS>",
"ACTUAL_HTTP_TOKEN": "<ACTUAL_HTTP_TOKEN>",
"ACTUAL_HTTP_WRITE_TOKEN": "<ACTUAL_HTTP_WRITE_TOKEN>"
}
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"actual-budget-mcp": {
"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>",
"ACTUAL_ENCRYPTION_PASSWORDS": "<ACTUAL_ENCRYPTION_PASSWORDS>",
"ACTUAL_HTTP_TOKEN": "<ACTUAL_HTTP_TOKEN>",
"ACTUAL_HTTP_WRITE_TOKEN": "<ACTUAL_HTTP_WRITE_TOKEN>"
}
}
}
}Add to .vscode/mcp.json
{
"servers": {
"actual-budget-mcp": {
"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>",
"ACTUAL_ENCRYPTION_PASSWORDS": "<ACTUAL_ENCRYPTION_PASSWORDS>",
"ACTUAL_HTTP_TOKEN": "<ACTUAL_HTTP_TOKEN>",
"ACTUAL_HTTP_WRITE_TOKEN": "<ACTUAL_HTTP_WRITE_TOKEN>"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"actual-budget-mcp": {
"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>",
"ACTUAL_ENCRYPTION_PASSWORDS": "<ACTUAL_ENCRYPTION_PASSWORDS>",
"ACTUAL_HTTP_TOKEN": "<ACTUAL_HTTP_TOKEN>",
"ACTUAL_HTTP_WRITE_TOKEN": "<ACTUAL_HTTP_WRITE_TOKEN>"
}
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"actual-budget-mcp": {
"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>",
"ACTUAL_ENCRYPTION_PASSWORDS": "<ACTUAL_ENCRYPTION_PASSWORDS>",
"ACTUAL_HTTP_TOKEN": "<ACTUAL_HTTP_TOKEN>",
"ACTUAL_HTTP_WRITE_TOKEN": "<ACTUAL_HTTP_WRITE_TOKEN>"
}
}
}
}Configuration
ACTUAL_SERVER_URLURL of your Actual Budget server, for example http://localhost:5006RequiredACTUAL_PASSWORDPassword for your Actual Budget server. Not needed if you set ACTUAL_SESSION_TOKENACTUAL_SESSION_TOKENSession token for servers behind OIDC, which have no password. Use instead of ACTUAL_PASSWORD; if both are set, the token winsACTUAL_BUDGET_IDYour budget's Sync ID, found under Settings > Show advanced settingsRequiredACTUAL_ENCRYPTION_PASSWORDOnly needed if your budget file is end-to-end encryptedACTUAL_BUDGET_IDSEvery budget this server serves, comma separated, when it is more than one. Each tool then takes a budget_id, and each budget is opened in a process of its ownACTUAL_ENCRYPTION_PASSWORDSA JSON object of budget sync id to encryption password, for when more than one of the budgets is encrypted. Each worker is given its own and never the mapACTUAL_BUDGET_WORKERSHow many budgets stay open at once. Defaults to 3. A fourth budget closes the one that went longest without a callACTUAL_WORKER_IDLE_MINUTESHow long an open budget with nothing to do stays open. Defaults to 15ACTUAL_WORKER_READY_SECONDSHow long a call waits for a budget that is still opening before it answers that it is still opening. Defaults to 45ACTUAL_READ_ONLYSet to 1 to hide every write tool from the model, exposing only reads and analysisACTUAL_TOOLSETSet to chat to offer the 18 everyday tools instead of all 44, which is 17.4 KiB of tool descriptions instead of 39.7 KiB on every connection. Defaults to fullACTUAL_DATA_DIRDirectory for the local budget cacheACTUAL_HTTP_TIMEOUT_MSHow long to wait for your server to start replying, in milliseconds. Defaults to 60000; raise it if a GoCardless bank sync is being cut offACTUAL_HTTP_PORTServe MCP over HTTP on this port instead of stdio. Only for a server you run yourself and point clients at: a client that starts this package itself speaks stdio and cannot reach it once this is setACTUAL_HTTP_TOKENThe credential for the read path, /mcp. Required once ACTUAL_HTTP_PORT is set, and at least 32 charactersACTUAL_HTTP_WRITE_TOKENA second credential, for the write path, /mcp-write. Without it the server serves no write path at allACTUAL_HTTP_HOSTWhat to bind to. Defaults to 127.0.0.1; inside a container that is unreachable, so 0.0.0.0 together with ACTUAL_HTTP_ALLOW_REMOTEACTUAL_HTTP_ALLOW_REMOTESet to 1 to bind somewhere other than loopback. Nothing here terminates TLS, so put something in front of it that doesACTUAL_HTTP_ALLOWED_HOSTSHostnames to accept in the Host header, comma separated and without ports, for a server that is not on loopback. Anything else is answered 403ACTUAL_SERVER_URLURL of your Actual Budget server. Inside the container localhost is the container, so use host.docker.internalRequiredACTUAL_PASSWORDPassword for your Actual Budget server. Not needed if you set ACTUAL_SESSION_TOKENACTUAL_SESSION_TOKENSession token for servers behind OIDC, which have no password. Use instead of ACTUAL_PASSWORD; if both are set, the token winsACTUAL_BUDGET_IDYour budget's Sync ID, found under Settings > Show advanced settingsRequiredACTUAL_BUDGET_IDSEvery budget this server serves, comma separated, when it is more than one. Each tool then takes a budget_id, and each budget is opened in a process of its ownACTUAL_ENCRYPTION_PASSWORDSA JSON object of budget sync id to encryption password, for when more than one of the budgets is encrypted. Each worker is given its own and never the mapACTUAL_BUDGET_WORKERSHow many budgets stay open at once. Defaults to 3. A fourth budget closes the one that went longest without a callACTUAL_WORKER_IDLE_MINUTESHow long an open budget with nothing to do stays open. Defaults to 15ACTUAL_WORKER_READY_SECONDSHow long a call waits for a budget that is still opening before it answers that it is still opening. Defaults to 45ACTUAL_READ_ONLYSet to 1 to hide every write tool from the model, exposing only reads and analysisACTUAL_TOOLSETSet to chat to offer the 18 everyday tools instead of all 44, which is 17.4 KiB of tool descriptions instead of 39.7 KiB on every connection. Defaults to fullACTUAL_HTTP_TIMEOUT_MSHow long to wait for your server to start replying, in milliseconds. Defaults to 60000; raise it if a GoCardless bank sync is being cut offACTUAL_HTTP_PORTServe MCP over HTTP on this port instead of stdio. Only for a server you run yourself and point clients at: a client that starts this package itself speaks stdio and cannot reach it once this is setACTUAL_HTTP_TOKENThe credential for the read path, /mcp. Required once ACTUAL_HTTP_PORT is set, and at least 32 charactersACTUAL_HTTP_WRITE_TOKENA second credential, for the write path, /mcp-write. Without it the server serves no write path at allACTUAL_HTTP_HOSTWhat to bind to. Defaults to 127.0.0.1; inside a container that is unreachable, so 0.0.0.0 together with ACTUAL_HTTP_ALLOW_REMOTEACTUAL_HTTP_ALLOW_REMOTESet to 1 to bind somewhere other than loopback. Nothing here terminates TLS, so put something in front of it that doesACTUAL_HTTP_ALLOWED_HOSTSHostnames to accept in the Host header, comma separated and without ports, for a server that is not on loopback. Anything else is answered 403
Tools this server provides (1)
Taken from the project documentation; the running server may differ.
- repair_sync
- Rebuilds the local sync state when the Actual API and your server disagree.
What it does
- Budget analysis
- Gives projections, category trends, budget vs actual and month summaries.
- Delete previews
- Shows what a delete will remove and waits for confirmation first.
- Duplicate checks
- Checks new transactions for duplicates before they are created.
- Read-only mode
- Hides every write tool from the model when ACTUAL_READ_ONLY is set to 1.
- Sync repair
- Rebuilds local sync state when the API and server disagree.
- Multi-budget support
- Serves several budgets, each opened in its own worker process.
- Smaller toolset
- A chat mode offers 18 everyday tools instead of all 44.
Good for
- Ask where the money went this month and get a breakdown
- Check whether spending is on track to stay within budget
- Move budget amounts between categories in conversation
- Add, split or transfer transactions without opening the app
- Run a budget assistant with write tools disabled
Pricing
Open source
Free, MIT licensed; requires your own Actual Budget server
Prices change. Check actual-mcp.henfrydls.com before you buy.
Actual Budget FAQ
What do I need to run it?
An Actual Budget server, its URL and password or session token, and the budget Sync ID from Settings > Show advanced settings.
Can it make changes safely?
Deletes preview first and wait for confirmation, and ACTUAL_READ_ONLY=1 removes write tools entirely.
Does it work with ChatGPT?
Not currently. ChatGPT connectors use OAuth, while this server takes a fixed token over HTTP.
Does it work with local models?
Yes, with any MCP client, including one pointed at Ollama or LM Studio, which keeps budget data on your machine.
Which Node version is needed?
Node.js 22.14 or newer, except for the Claude Desktop extension, which uses the Node bundled with Claude Desktop.
Is Actual Budget free?
Yes. Actual Budget is open source, so you can use and self-host it for free.
How do I add Actual Budget to Claude Code?
Run this command in your terminal: claude mcp add actual-budget-mcp --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>' --env ACTUAL_ENCRYPTION_PASSWORDS='<ACTUAL_ENCRYPTION_PASSWORDS>' --env ACTUAL_HTTP_TOKEN='<ACTUAL_HTTP_TOKEN>' --env ACTUAL_HTTP_WRITE_TOKEN='<ACTUAL_HTTP_WRITE_TOKEN>' -- npx -y actual-budget-mcp
What are the best alternatives to Actual Budget?
The closest alternatives to Actual Budget are Solana MCP by Vybe, Tapetide - Indian Stock Market MCP, Budget Tracker, Quantivex Research and Provyan.
Alternatives to Actual Budget

Solana MCP by Vybe
MCP serverRemote MCP server exposing the Vybe Solana API to AI clients and code editors
- 44 tools
- Remote
- 2.8K GitHub stars
- Finance and payments

Tapetide - Indian Stock Market MCP
MCP serverIndian NSE and BSE stock market data for AI assistants through 48 MCP tools
- 17 tools
- Remote
- Freemium
- 150 GitHub stars
- Finance and payments
Budget Tracker
MCP serverLocal MCP expense ledger that logs receipts and mileage, splits VAT and prepares rebilling
- 14 tools
- Remote
- Freemium
- 2 GitHub stars
- Finance and payments

Quantivex Research
MCP serverStock scores, what a price assumes, earnings quality and quiet profit revisions
- 11 tools
- Remote
- Free
- Finance and payments

Provyan
MCP serverBacktested crypto signal results on 94 coins, with luck odds and sources
- 4 tools
- Remote
- Free
- Finance and payments
TribuJus
MCP serverRead-only access to UK bank accounts, cards and transactions via TrueLayer Open Banking
Not checked yet- 5 tools
- Remote
- Open source
- Legal and government