actual-budget

This MCP server exposes the Actual Budget API tools over HTTP using the Model Context Protocol (MCP) with streaming support via Server-Sent Events (SSE). The server runs at /mcp and provides endpoints for core Actual Budget tools such as Accounts, Transactions, Categories, Payees, Rules, reporting, and AI-style summaries. To enable real usage, you must provide your Actual server credentials (ACTUAL_SERVER_URL, ACTUAL_PASSWORD, ACTUAL_SYNC_ID). The server supports three authentication modes (bearer, oauth, none); you can configure these via environment variables. Once running, clients connect to /mcp and can subscribe to streaming responses for long-running tool calls, or fetch discrete results depending on the endpoint you invoke.

After starting, the server will listen on http://localhost:3000/mcp by default (unless overridden by MCP_PORT). Use your preferred MCP client to issue tool calls, subscribe to results, and manage data through the provided Accounts, Transactions, Categories, Payees, Rules, and reporting tooling, as well as AI-style summaries generated from your data.

Prerequisites:

• Node.js 18+ installed
• npm installed
• Actual credentials: ACTUAL_SERVER_URL, ACTUAL_PASSWORD, ACTUAL_SYNC_ID (required at runtime)

Install the package dependencies:

npm install

Configure environment variables (example for development):

export ACTUAL_SERVER_URL=https://your-actual
export ACTUAL_PASSWORD=your-password
export ACTUAL_SYNC_ID=your-sync-id

Build and run in development:

npm run build
npm start

Alternative development run (explicit dev script):

export ACTUAL_SERVER_URL=https://your-actual
export ACTUAL_PASSWORD=your-password
export ACTUAL_SYNC_ID=your-sync-id
npm run dev

Docker usage (examples):

npm run docker:run
# or manually
npm run docker:build
docker run --rm -p 3000:3000 \
  -e MCP_PORT=3000 \
  -e ACTUAL_SERVER_URL=https://your-actual \
  -e ACTUAL_PASSWORD=... \
  -e ACTUAL_SYNC_ID=... \
  ghcr.io/trek-boldly-go/actual-budget-mcp-server:latest

If you prefer to run via Docker Compose (MCP + Keycloak OAuth), use:

docker compose up -d

• The server uses the Actual API credentials provided via ACTUAL_SERVER_URL, ACTUAL_PASSWORD, and ACTUAL_SYNC_ID. Ensure these are kept secure and not committed.
• Default MCP port is 3000; you can override with MCP_PORT.
• For OAuth, Bearer, or none authentication modes, configure MCP_AUTH_MODE accordingly and provide any required tokens or client credentials.
• The MCP exposes streaming responses via SSE; ensure your MCP client handles EventSource or equivalent streaming interfaces.
• When running in Docker, you may override the platform with MCP_DOCKER_PLATFORM if needed (linux/amd64 by default).
• If you enable Docker Compose with Keycloak, provide your Keycloak realm and client settings via environment variables as described in the repo docs.