MCP Hub › Developer Tools › Actual Budget

Actual Budget MCP server

by henfrydls · io.github.henfrydls/actual-budget-mcp

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

🛠 Developer ToolsDockernpmv0.12.0
Open in MCP HubGitHub repository ↗Website ↗

How to install Actual Budget

npm

claude mcp add -e ACTUAL_SERVER_URL=<your-actual-server-url> -e ACTUAL_BUDGET_ID=<your-actual-budget-id> actual-budget-mcp -- npx -y [email protected]

Or add it to your MCP config (Claude Desktop, Cursor, VS Code):

{
  "mcpServers": {
    "actual-budget-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]"
      ],
      "env": {
        "ACTUAL_SERVER_URL": "<your-actual-server-url>",
        "ACTUAL_BUDGET_ID": "<your-actual-budget-id>"
      }
    }
  }
}

Environment variables:
ACTUAL_SERVER_URL (required) – URL of your Actual Budget server, for example http://localhost:5006
ACTUAL_PASSWORD – Password for your Actual Budget server. Not needed if you set ACTUAL_SESSION_TOKEN
ACTUAL_SESSION_TOKEN – 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 – Only needed if your budget file is end-to-end encrypted
ACTUAL_BUDGET_IDS – 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 – 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 – 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 – How long an open budget with nothing to do stays open. Defaults to 15
ACTUAL_WORKER_READY_SECONDS – 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 – Set to 1 to hide every write tool from the model, exposing only reads and analysis
ACTUAL_TOOLSET – 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 – Directory for the local budget cache
ACTUAL_HTTP_TIMEOUT_MS – 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 – 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 – The credential for the read path, /mcp. Required once ACTUAL_HTTP_PORT is set, and at least 32 characters
ACTUAL_HTTP_WRITE_TOKEN – A second credential, for the write path, /mcp-write. Without it the server serves no write path at all
ACTUAL_HTTP_HOST – 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 – 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 – 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

Docker

claude mcp add -e ACTUAL_SERVER_URL=<your-actual-server-url> -e ACTUAL_BUDGET_ID=<your-actual-budget-id> actual-budget-mcp -- docker run -i --rm ghcr.io/henfrydls/actual-budget-mcp:0.12.0

Or add it to your MCP config (Claude Desktop, Cursor, VS Code):

{
  "mcpServers": {
    "actual-budget-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/henfrydls/actual-budget-mcp:0.12.0"
      ],
      "env": {
        "ACTUAL_SERVER_URL": "<your-actual-server-url>",
        "ACTUAL_BUDGET_ID": "<your-actual-budget-id>"
      }
    }
  }
}

Environment variables:
ACTUAL_SERVER_URL (required) – URL of your Actual Budget server. Inside the container localhost is the container, so use host.docker.internal
ACTUAL_PASSWORD – Password for your Actual Budget server. Not needed if you set ACTUAL_SESSION_TOKEN
ACTUAL_SESSION_TOKEN – 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_BUDGET_IDS – 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 – 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 – 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 – How long an open budget with nothing to do stays open. Defaults to 15
ACTUAL_WORKER_READY_SECONDS – 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 – Set to 1 to hide every write tool from the model, exposing only reads and analysis
ACTUAL_TOOLSET – 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_HTTP_TIMEOUT_MS – 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 – 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 – The credential for the read path, /mcp. Required once ACTUAL_HTTP_PORT is set, and at least 32 characters
ACTUAL_HTTP_WRITE_TOKEN – A second credential, for the write path, /mcp-write. Without it the server serves no write path at all
ACTUAL_HTTP_HOST – 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 – 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 – 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

Replace placeholders in <angle brackets> with your own values. Review what a server can access before you enable it.

Details

Version
0.12.0
Published
2026-11-04
Updated
2026-11-04
Namespace
io.github.henfrydls
Source
henfrydls/actual-budget-mcp

Similar developer tools servers