Connect Actual Budget to Claude

Claude cannot see your Actual Budget on its own. An MCP server sits between the two: Claude asks it questions, it reads your budget from your own Actual server, and nothing is sent anywhere else.

Before you start

• An Actual Budget server you can reach, local or remote, with the password set in Settings.
• Node.js 22 or newer (node --version to check).
• Claude Desktop or Claude Code installed.

1. Copy the Sync ID from Actual

1. Open Actual Budget.
2. Open Settings: click the arrow next to your budget name, or use the sidebar, More, then Settings.
3. Click Show advanced settings.
4. Copy the Sync ID.

Take the Sync ID, not the Budget ID. Actual shows both, one under the other, and both look like UUIDs. The variable is called ACTUAL_BUDGET_ID but it wants the Sync ID. If Sync ID shows (none), the budget has never been synced to a server and needs to be synced first.

2. Add the server to Claude

Claude Desktop: install the extension

The shortest route, and the one to take unless you have a reason not to. Download actual-budget-mcp.mcpb, then in Claude Desktop open Settings, go to Extensions, and drag the file onto that screen. Claude asks for your server URL, Sync ID and password in a form, and keeps the password in your operating system's credential store.

On Windows, drag the file into that screen: double-clicking it does not open Claude, because the app does not register the .mcpb file type. The extension carries everything it needs and does not compile anything, so it needs Node.js 22 or newer and nothing else. It is 56 MB, downloaded once.

Prefer to edit the configuration by hand, or use a different client? The rest of this step covers that.

Claude Code

One command. Replace the three values with yours:

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

Claude Desktop, by hand

Only if you would rather not use the extension. Open the config file and add the actual-budget-mcp entry under mcpServers. Create the file if it does not exist.

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-sync-id"
      }
    }
  }
}

Which port? A self-hosted sync server is usually 5006. The desktop app runs its own server on 5007, only while the app is open, and only for the same machine: from another computer or a virtual machine you need an SSH tunnel to it.

If your budget file is encrypted, add "ACTUAL_ENCRYPTION_PASSWORD" to the same env block. Cursor, VS Code and Docker instructions are in the README.

Signing in through OIDC? Your server has no password to put here. Use ACTUAL_SESSION_TOKEN instead of ACTUAL_PASSWORD, from version 0.9.0 on.

3. Restart the client

Claude Desktop and Claude Code read MCP configuration when they start, so an edit is not picked up until you quit and reopen them. This is the step most people miss. The extension does not need this: it starts when you enable it.

4. Ask something

Try "What did I spend on groceries last month?" or "Which categories am I over budget in?" The first answer takes a few seconds while the server downloads your budget; after that it is quick.

Where it keeps your budget

The server downloads a copy of your budget so it does not have to fetch it again on every question. It lives in ~/.local/share/actual-budget-mcp on Linux, ~/Library/Application Support/actual-budget-mcp on macOS and %APPDATA%\actual-budget-mcp on Windows. It is a cache, not your data: deleting it costs one re-download, and your budget stays on your Actual server. Point ACTUAL_DATA_DIR somewhere else if you prefer. Versions before 0.9.0 kept it in a folder under /tmp, which many systems empty on reboot.

If it does not work

Run the same package with --verify in a terminal. It connects, downloads the budget and prints how many accounts and category groups it found:

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

• Budget "..." not found on the server almost always means you copied the Budget ID instead of the Sync ID.
• A connection error means the URL is wrong or the Actual server is not reachable from this machine. If you use the desktop app, the port is 5007, not 5006, and the app has to be open.
• If Claude still lists no tools after the check passes, the client was not restarted.

Still stuck? Open an issue with the output of --verify, without your password.

What Claude can do once connected

Read accounts, transactions, categories and budgets; compare budget against actual, show trends and project spending; and write when you ask it to: add or fix transactions, move money between categories, manage payees and rules. Every delete previews what it will remove and waits for you to confirm. There is also an opt-in read-only mode if you only want questions answered. The full list of tools is on the home page.