开源MCP工具：Docker MCP server

Prerequisites

• Actual Budget server running (local or remote)
• Your Budget Sync ID: Actual → Settings → Show Advanced Settings → Sync ID
• Node.js 20+ (npm method) or Docker

Option A: Docker (recommended)

docker run -d \
  --name actual-mcp-server-backend \
  -p 3600:3600 \
  # Use the same URL you type in your browser to open Actual Budget:
  #   http://localhost:5006          (if Actual Budget runs on the same machine)
  #   http://192.168.1.50:5006       (if it runs on another machine on your network)
  #   https://actual.yourdomain.com  (if you use a domain name)
  #   http://actual:5006             (if both containers share a Docker network; use container name)
  -e ACTUAL_SERVER_URL=http://localhost:5006 \
  -e ACTUAL_PASSWORD=your_password \
  -e ACTUAL_BUDGET_SYNC_ID=your_sync_id \
  -e MCP_SSE_AUTHORIZATION=your_secret_token \
  -v actual-mcp-data:/app/data \        # required, see note below
  -v actual-mcp-logs:/app/logs \
  ghcr.io/agigante80/actual-mcp-server:latest

Why the /app/data volume is required: Actual Budget does not expose a REST API. The official @actual-app/api library (used internally by this server) works by downloading a local copy of your budget data, running all queries on that local copy, then syncing changes back. The /app/data volume gives the container a persistent, writable place to store that local copy (it is the directory the image creates and owns as the runtime user). Without it the container has nowhere to write and will fail on startup. See the Actual API docs for details. actual-mcp does not need to run on the same machine as Actual Budget. You can have Actual Budget on one server and actual-mcp on another - as long as ACTUAL_SERVER_URL points to your Actual Budget instance, everything works.

Verify it's running:

```bash

Option B: Docker Compose

```bash git clone https://github.com/agigante80/actual-mcp-server.git cd actual-mcp-server cp .env.example .env # fill in ACTUAL_SERVER_URL, ACTUAL_PASSWORD, ACTUAL_BUDGET_SYNC_ID

docker compose --profile production up -d # production: MCP server listens on :3600

Option D: stdio (Claude Desktop native, no Docker or HTTP server needed)

The stdio transport runs the MCP server as a child process. Claude Desktop spawns it directly and communicates over stdin/stdout. No network port, no auth token, no Docker required. No cloning needed: npx downloads and caches the package automatically.

Add to claude_desktop_config.json (see docs/guides/MCP_CLIENTS_SETUP.md for config file location and all client options):

{
  "mcpServers": {
    "actual-budget": {
      "command": "npx",
      "args": ["-y", "actual-mcp-server", "--stdio"],
      "env": {
        "ACTUAL_SERVER_URL": "http://localhost:5006",
        "ACTUAL_PASSWORD": "your_actual_password",
        "ACTUAL_BUDGET_SYNC_ID": "your-sync-id-here",
        "MCP_BRIDGE_DATA_DIR": "/absolute/path/to/data-dir"
      }
    }
  }
}

No token needed. stdio runs as a local process owned by your user. The transport itself is the security boundary. All 71 tools are available. MCP_BRIDGE_DATA_DIR should be an absolute path. Without one, the data directory resolves relative to wherever the client spawns the process, which can be unpredictable. The directory is created automatically on first run.

Docker (Option A)

```bash docker pull ghcr.io/agigante80/actual-mcp-server:latest docker stop actual-mcp-server-backend docker rm actual-mcp-server-backend

Re-run the original docker run command with the same flags and volumes

```

Also available on Docker Hub: docker pull agigante80/actual-mcp-server:latest

Docker Compose (Option B)

docker compose pull
docker compose --profile production up -d

Upgrade the global install

npm install -g actual-mcp-server

Or force the registry version without touching your global install

npx actual-mcp-server@latest --http ```

For Claude Desktop (stdio), restart Claude after upgrading.

---

Quick Start

Quick start via npx (no clone needed):

ACTUAL_SERVER_URL=http://localhost:5006 \ ACTUAL_PASSWORD=your_password \ ACTUAL_BUDGET_SYNC_ID=your-sync-id \ MCP_SSE_AUTHORIZATION=your_token \ npx actual-mcp-server --http

Option C: npm (HTTP server)

```bash

Or clone for development / custom config:

git clone https://github.com/agigante80/actual-mcp-server.git cd actual-mcp-server npm install cp .env.example .env # fill in required values npm run build npm run dev -- --http ```

Server starts at http://localhost:3600/http by default (the listen port is MCP_BRIDGE_PORT, default 3600).

npm / cloned repo (Option C)

```bash git pull npm install npm run build

npx / stdio (Options C & D)

If you run npx actual-mcp-server without a globally installed version, npx fetches the latest from the registry automatically. But if you previously installed it globally (npm install -g actual-mcp-server), the global install takes precedence, so you must upgrade it explicitly:

```bash

Configuration

All configuration is via environment variables. Copy .env.example to .env to get started.

Complete Environment Variables Reference

---

Add to .env

MCP_SSE_AUTHORIZATION=your_token_here

Clients send: `Authorization: Bearer your_token_here`

#### OIDC (multi-user)

See AI Client Setup, OIDC for AUTH_BUDGET_ACL format and Casdoor notes.

---

Comparison with Similar Projects

Several MCP servers exist for personal finance management. Here's how this project compares with the closest alternatives.

Snapshot date: 2026-03-20. Versions and features reflect each project's latest release at that date.

Feature Comparison