Actual Budget

io.github.henfrydls/actual-budget-mcp · v0.12.0

Actual Budget, carefully: deletes preview first, and new transactions check for duplicates.

Website Source code Set it up

Connect Runs on your machine

Terminal

claude mcp add actual-budget-mcp -e ACTUAL_SERVER_URL=<ACTUAL_SERVER_URL> -e ACTUAL_PASSWORD=<ACTUAL_PASSWORD> -e ACTUAL_SESSION_TOKEN=<ACTUAL_SESSION_TOKEN> -e ACTUAL_BUDGET_ID=<ACTUAL_BUDGET_ID> -e ACTUAL_ENCRYPTION_PASSWORD=<ACTUAL_ENCRYPTION_PASSWORD> -e ACTUAL_BUDGET_IDS=<ACTUAL_BUDGET_IDS> -e ACTUAL_ENCRYPTION_PASSWORDS=<ACTUAL_ENCRYPTION_PASSWORDS> -e ACTUAL_BUDGET_WORKERS=<ACTUAL_BUDGET_WORKERS> -e ACTUAL_WORKER_IDLE_MINUTES=<ACTUAL_WORKER_IDLE_MINUTES> -e ACTUAL_WORKER_READY_SECONDS=<ACTUAL_WORKER_READY_SECONDS> -e ACTUAL_READ_ONLY=<ACTUAL_READ_ONLY> -e ACTUAL_TOOLSET=<ACTUAL_TOOLSET> -e ACTUAL_DATA_DIR=<ACTUAL_DATA_DIR> -e ACTUAL_HTTP_TIMEOUT_MS=<ACTUAL_HTTP_TIMEOUT_MS> -e ACTUAL_HTTP_PORT=<ACTUAL_HTTP_PORT> -e ACTUAL_HTTP_TOKEN=<ACTUAL_HTTP_TOKEN> -e ACTUAL_HTTP_WRITE_TOKEN=<ACTUAL_HTTP_WRITE_TOKEN> -e ACTUAL_HTTP_HOST=<ACTUAL_HTTP_HOST> -e ACTUAL_HTTP_ALLOW_REMOTE=<ACTUAL_HTTP_ALLOW_REMOTE> -e ACTUAL_HTTP_ALLOWED_HOSTS=<ACTUAL_HTTP_ALLOWED_HOSTS> -- npx -y [email protected]

claude_desktop_config.json

{
  "mcpServers": {
    "actual-budget-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]"
      ],
      "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_BUDGET_IDS": "<ACTUAL_BUDGET_IDS>",
        "ACTUAL_ENCRYPTION_PASSWORDS": "<ACTUAL_ENCRYPTION_PASSWORDS>",
        "ACTUAL_BUDGET_WORKERS": "<ACTUAL_BUDGET_WORKERS>",
        "ACTUAL_WORKER_IDLE_MINUTES": "<ACTUAL_WORKER_IDLE_MINUTES>",
        "ACTUAL_WORKER_READY_SECONDS": "<ACTUAL_WORKER_READY_SECONDS>",
        "ACTUAL_READ_ONLY": "<ACTUAL_READ_ONLY>",
        "ACTUAL_TOOLSET": "<ACTUAL_TOOLSET>",
        "ACTUAL_DATA_DIR": "<ACTUAL_DATA_DIR>",
        "ACTUAL_HTTP_TIMEOUT_MS": "<ACTUAL_HTTP_TIMEOUT_MS>",
        "ACTUAL_HTTP_PORT": "<ACTUAL_HTTP_PORT>",
        "ACTUAL_HTTP_TOKEN": "<ACTUAL_HTTP_TOKEN>",
        "ACTUAL_HTTP_WRITE_TOKEN": "<ACTUAL_HTTP_WRITE_TOKEN>",
        "ACTUAL_HTTP_HOST": "<ACTUAL_HTTP_HOST>",
        "ACTUAL_HTTP_ALLOW_REMOTE": "<ACTUAL_HTTP_ALLOW_REMOTE>",
        "ACTUAL_HTTP_ALLOWED_HOSTS": "<ACTUAL_HTTP_ALLOWED_HOSTS>"
      }
    }
  }
}

~/.cursor/mcp.json

{
  "mcpServers": {
    "actual-budget-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]"
      ],
      "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_BUDGET_IDS": "<ACTUAL_BUDGET_IDS>",
        "ACTUAL_ENCRYPTION_PASSWORDS": "<ACTUAL_ENCRYPTION_PASSWORDS>",
        "ACTUAL_BUDGET_WORKERS": "<ACTUAL_BUDGET_WORKERS>",
        "ACTUAL_WORKER_IDLE_MINUTES": "<ACTUAL_WORKER_IDLE_MINUTES>",
        "ACTUAL_WORKER_READY_SECONDS": "<ACTUAL_WORKER_READY_SECONDS>",
        "ACTUAL_READ_ONLY": "<ACTUAL_READ_ONLY>",
        "ACTUAL_TOOLSET": "<ACTUAL_TOOLSET>",
        "ACTUAL_DATA_DIR": "<ACTUAL_DATA_DIR>",
        "ACTUAL_HTTP_TIMEOUT_MS": "<ACTUAL_HTTP_TIMEOUT_MS>",
        "ACTUAL_HTTP_PORT": "<ACTUAL_HTTP_PORT>",
        "ACTUAL_HTTP_TOKEN": "<ACTUAL_HTTP_TOKEN>",
        "ACTUAL_HTTP_WRITE_TOKEN": "<ACTUAL_HTTP_WRITE_TOKEN>",
        "ACTUAL_HTTP_HOST": "<ACTUAL_HTTP_HOST>",
        "ACTUAL_HTTP_ALLOW_REMOTE": "<ACTUAL_HTTP_ALLOW_REMOTE>",
        "ACTUAL_HTTP_ALLOWED_HOSTS": "<ACTUAL_HTTP_ALLOWED_HOSTS>"
      }
    }
  }
}

.vscode/mcp.json

{
  "servers": {
    "actual-budget-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "[email protected]"
      ],
      "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_BUDGET_IDS": "<ACTUAL_BUDGET_IDS>",
        "ACTUAL_ENCRYPTION_PASSWORDS": "<ACTUAL_ENCRYPTION_PASSWORDS>",
        "ACTUAL_BUDGET_WORKERS": "<ACTUAL_BUDGET_WORKERS>",
        "ACTUAL_WORKER_IDLE_MINUTES": "<ACTUAL_WORKER_IDLE_MINUTES>",
        "ACTUAL_WORKER_READY_SECONDS": "<ACTUAL_WORKER_READY_SECONDS>",
        "ACTUAL_READ_ONLY": "<ACTUAL_READ_ONLY>",
        "ACTUAL_TOOLSET": "<ACTUAL_TOOLSET>",
        "ACTUAL_DATA_DIR": "<ACTUAL_DATA_DIR>",
        "ACTUAL_HTTP_TIMEOUT_MS": "<ACTUAL_HTTP_TIMEOUT_MS>",
        "ACTUAL_HTTP_PORT": "<ACTUAL_HTTP_PORT>",
        "ACTUAL_HTTP_TOKEN": "<ACTUAL_HTTP_TOKEN>",
        "ACTUAL_HTTP_WRITE_TOKEN": "<ACTUAL_HTTP_WRITE_TOKEN>",
        "ACTUAL_HTTP_HOST": "<ACTUAL_HTTP_HOST>",
        "ACTUAL_HTTP_ALLOW_REMOTE": "<ACTUAL_HTTP_ALLOW_REMOTE>",
        "ACTUAL_HTTP_ALLOWED_HOSTS": "<ACTUAL_HTTP_ALLOWED_HOSTS>"
      }
    }
  }
}

Replace the values in angle brackets with your own. Keys stay on your machine; we never see them.

Tools

This server runs locally, so its tools are listed by your MCP client once it starts.

Environment variables

Name	Description
`ACTUAL_SERVER_URL` Required	URL of your Actual Budget server, for example http://localhost:5006
`ACTUAL_PASSWORD` Optional, secret	Password for your Actual Budget server. Not needed if you set ACTUAL_SESSION_TOKEN
`ACTUAL_SESSION_TOKEN` Optional, secret	Session token for servers behind OIDC, which have no password. Use instead of ACTUAL_PASSWORD; if both are set, the token wins
`ACTUAL_BUDGET_ID` Required	Your budget's Sync ID, found under Settings > Show advanced settings
`ACTUAL_ENCRYPTION_PASSWORD` Optional, secret	Only needed if your budget file is end-to-end encrypted
`ACTUAL_BUDGET_IDS` Optional	Every 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 own
`ACTUAL_ENCRYPTION_PASSWORDS` Optional, secret	A 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 map
`ACTUAL_BUDGET_WORKERS` Optional	How many budgets stay open at once. Defaults to 3. A fourth budget closes the one that went longest without a call
`ACTUAL_WORKER_IDLE_MINUTES` Optional	How long an open budget with nothing to do stays open. Defaults to 15
`ACTUAL_WORKER_READY_SECONDS` Optional	How long a call waits for a budget that is still opening before it answers that it is still opening. Defaults to 45
`ACTUAL_READ_ONLY` Optional	Set to 1 to hide every write tool from the model, exposing only reads and analysis
`ACTUAL_TOOLSET` Optional	Set 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 full
`ACTUAL_DATA_DIR` Optional	Directory for the local budget cache
`ACTUAL_HTTP_TIMEOUT_MS` Optional	How long to wait for your server to start replying, in milliseconds. Defaults to 60000; raise it if a GoCardless bank sync is being cut off
`ACTUAL_HTTP_PORT` Optional	Serve 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 set
`ACTUAL_HTTP_TOKEN` Optional, secret	The credential for the read path, /mcp. Required once ACTUAL_HTTP_PORT is set, and at least 32 characters
`ACTUAL_HTTP_WRITE_TOKEN` Optional, secret	A second credential, for the write path, /mcp-write. Without it the server serves no write path at all
`ACTUAL_HTTP_HOST` Optional	What 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_REMOTE
`ACTUAL_HTTP_ALLOW_REMOTE` Optional	Set to 1 to bind somewhere other than loopback. Nothing here terminates TLS, so put something in front of it that does
`ACTUAL_HTTP_ALLOWED_HOSTS` Optional	Hostnames to accept in the Host header, comma separated and without ports, for a server that is not on loopback. Anything else is answered 403

Details

Package	`[email protected]` (NPM, stdio)
Package	`ghcr.io/henfrydls/actual-budget-mcp:0.12.0` (OCI, stdio)
First published	4 Nov 2026
Last updated	4 Nov 2026
Registry name	`io.github.henfrydls/actual-budget-mcp`

More other servers See all

Live status

Local install

Installed and run on your own machine, so there is no public endpoint to check.

Pair it with live search

Agents that use Actual Budget often also need current facts. NestDaddy MCP gives your AI today's internet: web search, real-time breaking news and full page reading in one connector.

See NestDaddy MCP

For maintainers

[![NestDaddy MCP](https://nestdaddy.com/mcp/servers/io-github-henfrydls-actual-budget-mcp/badge.svg)](https://nestdaddy.com/mcp/servers/io-github-henfrydls-actual-budget-mcp)

Add the badge to your README. It turns green while your server passes our daily check. Listing details come from the official MCP registry; update them there.

Listing data from the official MCP registry. Status and tools from NestDaddy's daily check. Browse all MCP servers.