Actual Budget

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 "Wallet" 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. ChatGPT's connectors only accept remote MCP servers: a public HTTPS endpoint speaking SSE or Streamable HTTP. With HTTP mode this server can be one. What we have read says their connectors sign in through OAuth or not at all and cannot send the fixed token header this version takes, and nobody here has tried it. 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:

Install the actual-budget-mcp MCP server from npm (https://github.com/henfrydls/actual-budget-mcp).

Configure it with these credentials:

• My Actual Budget server: http://localhost:5006
• Password: YOUR_PASSWORD
• Budget ID: YOUR_BUDGET_ID

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](https://github.com/henfrydls/actual-budget-mcp/releases/latest/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 extension on the Node it ships with. Checked by renaming Node out of the way on a Windows 11 machine and asking a question anyway: the server started and answered.

Earlier builds launched the package from npm instead. That made the download small and moved it to the first run, where nothing showed progress: Claude Desktop waited, decided the server was dead and said it could not connect, and the extension started working on its own a few minutes later. The bundle now includes Actual's SQLite binary for every platform it supports. They are N-API binaries, so one per platform serves every Node version, and nothing has to be chosen at startup.

Updating the extension

Installing a new version over an old one keeps the settings you filled in, with one exception seen in practice: the saved server password was cleared when a field's title changed between versions. If Claude cannot connect after an update, open the extension's settings and check the password field before looking anywhere else.

Option 2: Claude Code (one command)

claude mcp add actual-budget-mcp -e ACTUAL_SERVER_URL=http://localhost:5006 -e ACTUAL_PASSWORD=your-password -e ACTUAL_BUDGET_ID=your-budget-id -- npx -y actual-budget-mcp

Option 3: Claude Desktop (edit the config file)

Add this to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{

"mcpServers": { "actual-budget-mcp": { "command": "npx", "args": ["-y", "actual-budget-mcp"], "env": { "ACTUAL_SERVER_URL": "http://localhost:5006", "ACTUAL_PASSWORD": "your-password", "ACTUAL_BUDGET_ID": "your-budget-sync-id" } } } }

Option 4: Cursor

The button installs it with placeholder values. Open Cursor Settings > MCP afterwards and replace the three: your server URL, your password, and your budget's Sync ID. To do it all by hand instead, go to Cursor Settings > MCP > Add new MCP server and add:

{

"mcpServers": { "actual-budget-mcp": { "command": "npx", "args": ["-y", "actual-budget-mcp"], "env": { "ACTUAL_SERVER_URL": "http://localhost:5006", "ACTUAL_PASSWORD": "your-password", "ACTUAL_BUDGET_ID": "your-budget-sync-id" } } } }

Option 5: VS Code (GitHub Copilot)

Same as above: the button fills in placeholders, and you replace the three values afterwards. By hand, add this to your VS Code settings.json:

{

"mcp": { "servers": { "actual-budget-mcp": { "command": "npx", "args": ["-y", "actual-budget-mcp"], "env": { "ACTUAL_SERVER_URL": "http://localhost:5006", "ACTUAL_PASSWORD": "your-password", "ACTUAL_BUDGET_ID": "your-budget-sync-id" } } } } }

Option 6: Codex (OpenAI)

One command, and it writes the entry into ~/.codex/config.toml for you:

codex mcp add actual-budget-mcp \

--env ACTUAL_SERVER_URL=http://localhost:5006 \ --env ACTUAL_PASSWORD=your-password \ --env ACTUAL_BUDGET_ID=your-budget-sync-id \ -- npx -y actual-budget-mcp

Codex has no extension or bundle format, so this one-liner is the shortest route there is. codex mcp list shows it afterwards, and codex mcp remove actual-budget-mcp undoes it.

This is Codex the local agent, the CLI and the IDE extension. Codex in the browser runs on OpenAI's machines and cannot reach an Actual server on your network.

Option 7: Docker

The image speaks stdio like every other option, so your client starts the container and owns its lifetime:

{

"mcpServers": { "actual-budget-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "--add-host=host.docker.internal:host-gateway", "-v", "actual-budget-mcp-data:/data", "-e", "ACTUAL_SERVER_URL", "-e", "ACTUAL_PASSWORD", "-e", "ACTUAL_BUDGET_ID", "ghcr.io/henfrydls/actual-budget-mcp:latest" ], "env": { "ACTUAL_SERVER_URL": "http://host.docker.internal:5006", "ACTUAL_PASSWORD": "your-password", "ACTUAL_BUDGET_ID": "your-budget-sync-id" } } } }

Two things that bite everyone once:

• Inside the container, `localhost` is the container. Your Actual server is not there. host.docker.internal (