Actual Budget MCP

Name: Actual Budget MCP
Author: henfrydls

henfrydls

Queries and manages a self-hosted Actual Budget: spending breakdowns, category trends, projections and budget vs. actual, with guarded writes.

Setup

Choose your client, copy the config, then fill in any required environment variables.

Add to Cursor Add to VS Code

claude mcp add actual-budget-henfrydls --env ACTUAL_SERVER_URL='<ACTUAL_SERVER_URL>' --env ACTUAL_PASSWORD='<ACTUAL_PASSWORD>' --env ACTUAL_SESSION_TOKEN='<ACTUAL_SESSION_TOKEN>' --env ACTUAL_BUDGET_ID='<ACTUAL_BUDGET_ID>' --env ACTUAL_ENCRYPTION_PASSWORD='<ACTUAL_ENCRYPTION_PASSWORD>' -- npx -y actual-budget-mcp

~/.codex/config.toml

[mcp_servers.actual-budget-henfrydls]
command = "npx"
args = ["-y", "actual-budget-mcp"]
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>" }

# codex mcp add actual-budget-henfrydls --env ACTUAL_SERVER_URL='<ACTUAL_SERVER_URL>' --env ACTUAL_PASSWORD='<ACTUAL_PASSWORD>' --env ACTUAL_SESSION_TOKEN='<ACTUAL_SESSION_TOKEN>' --env ACTUAL_BUDGET_ID='<ACTUAL_BUDGET_ID>' --env ACTUAL_ENCRYPTION_PASSWORD='<ACTUAL_ENCRYPTION_PASSWORD>' -- npx -y actual-budget-mcp

~/.cursor/mcp.json

{
  "mcpServers": {
    "actual-budget-henfrydls": {
      "command": "npx",
      "args": [
        "-y",
        "actual-budget-mcp"
      ],
      "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>"
      }
    }
  }
}

.vscode/mcp.json

{
  "servers": {
    "actual-budget-henfrydls": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "actual-budget-mcp"
      ],
      "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>"
      }
    }
  }
}

~/.gemini/settings.json

{
  "mcpServers": {
    "actual-budget-henfrydls": {
      "command": "npx",
      "args": [
        "-y",
        "actual-budget-mcp"
      ],
      "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>"
      }
    }
  }
}

claude_desktop_config.json

{
  "mcpServers": {
    "actual-budget-henfrydls": {
      "command": "npx",
      "args": [
        "-y",
        "actual-budget-mcp"
      ],
      "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>"
      }
    }
  }
}

.trae/mcp.json

{
  "mcpServers": {
    "actual-budget-henfrydls": {
      "command": "npx",
      "args": [
        "-y",
        "actual-budget-mcp"
      ],
      "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>"
      }
    }
  }
}

Environment variables

ACTUAL_SERVER_URL
ACTUAL_PASSWORD
ACTUAL_SESSION_TOKEN
ACTUAL_BUDGET_ID
ACTUAL_ENCRYPTION_PASSWORD

Replace the placeholders with your own credentials and keep them out of version control.

Setup

Environment variables

Related