henfrydls/actual-budget-mcp

Talk to your budget. An MCP server that connects Actual Budget to Claude. Ask where the money went, get real analysis back, and let it write without holding your breath.
Listed in the official Actual Budget community projects.
Features
- **Real analysis, not just lookups** - Projections, category trends, budget vs actual, and month summaries
- **Writes you can trust** - Every delete previews what it will remove and waits for you to confirm; ACTUAL_READ_ONLY=1 hides the write tools from the model entirely (Safety)
- **Multi-currency that survives reality** - Splits and residual reconciliation, not just a currency symbol
- **Recovers from an out-of-sync budget** - repair_sync rebuilds the local sync state when @actual-app/api and your server disagree, the failure that otherwise leaves every tool erroring
- **Ask about your budget in plain language** - "How much did I spend on food this month?" or "Am I over budget on anything?"
- **Create and manage transactions** - Add expenses, transfers, and edits without opening the app
- **Manage categories, payees, and rules** - Full CRUD without opening the app
- **Use names, not IDs** - Say "Cartera" instead of a1b2c3d4-..., with helpful suggestions if ambiguous
- **Natural dates in English and Spanish** - "last month", "este mes", "hace 3 meses", "yesterday"
- **Clean formatted output** - Aligned tables and clear summaries, not raw JSON
- **Clear error messages** - If something's wrong, you'll know exactly what to fix
Does it work with local models?
Yes. This is an MCP server, so it works with any client that speaks MCP, and the model
behind that client is the client's business, not this server's. Claude Desktop, Claude
Code, Cursor and VS Code are the ones documented below because they are the ones people
ask about, but anything that can run an MCP client, including a local setup pointed at
Ollama or LM Studio, talks to it the same way.
Your budget data goes to whatever model your client uses. If that matters to you, and for
a lot of people running Actual it does, a local model keeps it on your machine.
Does it work with ChatGPT?
No, and the reason is not this server. ChatGPT's connectors only accept remote MCP
servers: a public HTTPS endpoint speaking SSE or Streamable HTTP. There is no way to
point ChatGPT at a process running on your own machine, which is what this server is.
OpenAI does offer a tunnel for local servers, but it is limited to enterprise plans.
Making it work would mean exposing your Actual server to the internet, which is the
opposite of what most people running Actual want. Anything that can start a local MCP
process works instead: Claude Desktop, Claude Code, Cursor, VS Code, Gemini CLI, or your
own setup pointed at a local model.
If what you actually want is OpenAI's model, use **Codex**, which does run MCP servers
locally over stdio. Option 6 is the one command it takes.
Prerequisites
- Actual Budget server running (local or remote)
- Node.js **22.14 or newer** for every option below **except the
Desktop Extension** (see Node.js requirement)
- The Desktop Extension needs nothing but Claude Desktop. It runs on the Node
that Claude Desktop ships, and the bundle carries a SQLite binary for every
platform it supports, so nothing is compiled either. Checked on Windows 11
with Claude Desktop 2.110.0 and Node removed from the machine.
Quick Start
On Claude Desktop, the shortest path is the
extension: no config file
to edit and no command to run. Otherwise, copy this into Claude Code or Claude
Desktop:
Claude will configure everything for you.
Installation
Option 1: Claude Desktop extension (no config files)
A packaged Desktop Extension is available: install it and Claude Desktop asks
for your server URL, password and Sync ID in its own settings UI, with the
password and session token stored in your operating system's keychain rather
than a config file you have to edit.
**Download actual-budget-mcp.mcpb**,
then open Claude Desktop, go to **Settings > Extensions**, and drag the file
onto that screen.
On Windows, dragging is the way in: double-clicking the file opens Windows'
"select an app to open this file" dialogue instead, because Claude Desktop does
not register the .mcpb file type. Verified on a clean Windows 11 install with
Claude Desktop 0.14.10.
The extension carries everything it needs, so the first question you ask is
answered straight away rather than after an install you cannot see. It is a
large download, once, with a progress bar.
You do not need Node.js installed for this route. Claude Desktop runs the