Actual MCP Server: Actual Budget for agents
Actual MCP Server
An MCP server with 85 tools for your self-hosted Actual Budget: spending, categories, rules and schedules by asking an agent
- 76 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The agent creates, edits and deletes transactions, categories and rules in a real budget
- The Actual password and spending data reach the client and the model provider
Install
- Works in
Manual install
npx actual-mcp-server --httpNeeds Node.js 22+ and a `.env` with Actual settings.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent creates, edits and deletes transactions, categories and rules in a real budget
- The Actual password and spending data reach the client and the model provider
This is third-party code. Review the repository files before installing.
What it does
Actual MCP Server connects MCP clients (Claude, LibreChat, LobeChat, Cursor) to your self-hosted Actual Budget. An agent answers questions such as how much went on groceries last month by payee, adds transactions and moves amounts between categories. The 85 tools are grouped into toolsets: context, transactions, analysis, budget, rules, schedules, structure (accounts, categories, payees, tags), the read-only `actual_query_run` and administration (budget switching, import, export, bank sync). Unneeded toolsets are switched off with `MCP_TOOLSETS`: for chat clients with a small tool limit there is a `chat` preset of 12 tools. The server runs over stdio or HTTP, authenticates with a static Bearer token or OIDC, serves up to 15 concurrent sessions and retries transient Actual errors three times with growing pauses. Deletes and merges are never retried.
Who it is for. People who keep a household budget in a self-hosted Actual Budget and want to review spending and edit categories with chat phrases.
Good fit when
- You want to ask where the money went this month and get a breakdown by payee
- A bank statement has to be imported and sorted into categories with `actual_rules_create_batch` rules
- A family needs shared access to the budget through LibreChat with separate rights per person
- The month budget needs shifting: move 200 from Dining Out to Emergency Fund
Not a fit when
- Your budget lives in YNAB or another program: the server works only with Actual Budget
- Your Actual server is older than 25.0.0 or Node.js is below 22: compatibility is not guaranteed
- You want a cloud service with no self-hosting: Actual has to be deployed by you
Example request
How much did I spend on groceries last month by payee? Add a 47.50 Whole Foods transaction to my checking account.MCP
- Transport
- stdio, http
- Authentication
- API key
Environment variables
ACTUAL_SERVER_URLrequired- Actual Budget server URL reachable from where the MCP server runs
ACTUAL_PASSWORDrequired, secret- Login password of the Actual server
ACTUAL_BUDGET_SYNC_IDrequired- Budget Sync ID from Actual settings
MCP_SSE_AUTHORIZATIONsecret- Bearer token that clients send
Limitations
It needs a running Actual Budget server 25.0.0 or newer and Node.js 22 or newer. The address in `ACTUAL_SERVER_URL` must be reachable from where the server runs: inside Docker `localhost` points at the container itself. The Actual server password and the budget Sync ID are required, plus `ACTUAL_BUDGET_PASSWORD` for an encrypted budget.
Budget data returned by tools goes to the model provider of your client. Without `MCP_SSE_AUTHORIZATION` the HTTP mode is open to any client on the network, so a token is always set in production. The project is independent and not affiliated with Actual Budget.
How to disable. Stop the container (`docker stop actual-mcp-server-backend`) or remove the server from client settings. Change the Actual password if the token was exposed.
FAQ
How do I run Actual MCP Server without Docker?
With `npx actual-mcp-server --http` in a folder with a filled `.env`; Node.js 22 or newer is required.
Which environment variables are needed?
`ACTUAL_SERVER_URL`, `ACTUAL_PASSWORD` and `ACTUAL_BUDGET_SYNC_ID` are required, and `MCP_SSE_AUTHORIZATION` sets the Bearer token for clients.
How do I cut the tool count for Gemini or LibreChat?
Set `MCP_TOOLSETS`, for example the `chat` preset with 12 tools. A hidden tool is also refused when called by name.
Where does budget data go?
The server contacts only your Actual and the OIDC provider, but tool results reach the model of your client.
Which sign-in methods does the HTTP mode support?
A static Bearer token in `MCP_SSE_AUTHORIZATION` or OIDC with JWT validation through JWKS; budget access is set per user.
Discussion
No questions or reviews yet.
Related
MCP serversAn MCP server for Actual Budget: agents read accounts and transactions, build spending reports and, with a flag, edit categories.
An MCP server for YNAB: an agent reads budgets and accounts and edits transactions with a personal token, launched via uvx.
An MCP server for LunchMoney personal finance: transactions, budgets, categories and accounts exposed to agents via API v2.
The official RiseUp MCP server: budget, transactions, account balances and mortgage data, read-only, in Claude Desktop
The server gives agents read access to your bank accounts and transactions through Enable Banking, without payment tools.
Financial Datasets MCP
Financial Datasets MCP Server
An MCP server for the Financial Datasets API: company financials, stock and crypto prices and news for the agent
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Actual MCP Server: Actual Budget for agents (this card) | no | API key | 76 | |
| Actual Budget MCP Server | no | key is optional | 286 | another server for the same Actual Budget; this one has 85 tools, toolsets and OIDC |
| YNAB MCP Server | no | API key | 100 | works with cloud YNAB, while Actual MCP Server targets self-hosted Actual |
README in short
The README gives a Docker HTTP quick start and an npx run, a table of toolsets, environment variables, a privacy section and links to guides for clients, deployment and authentication.