Actual Budget MCP Server

An enterprise-ready Model Context Protocol (MCP) server for Actual Budget.

This server enables AI assistants and autonomous agents (such as Claude Desktop, Google Antigravity, Cursor, and custom orchestrators) to securely query, reconcile, analyze, and manage personal finances using the official Actual Budget API.

Features

• Dual Transport Protocols:

  • Stdio Transport: Native standard input/output transport for desktop tools (Claude Desktop, Cursor, local agent runners).

  • Streamable HTTP Transport (MCP spec 2025-11-25): Modern, multi-session HTTP endpoint (/mcp) supporting stateful sessions, SSE, and remote agents.

• Production-Ready OAuth2 Authentication:

  • RFC 8414 & OpenID Connect Discovery metadata endpoints.

  • RFC 9728 OAuth 2.0 Protected Resource Metadata (/.well-known/oauth-protected-resource).

  • Authorization Code Grant with PKCE (S256), Refresh Token Grant, and RFC 7009 Token Revocation.

  • Persistent SQLite token storage (data/auth.sqlite) with WAL mode, auto-expiration, and security audit activity logging.

  • Redirect URI domain restriction (ALLOWED_REDIRECT_DOMAINS).

  • Optional --no-auth mode for private or local networks.

• High Performance & Resilience:

  • Persistent in-process connection via official @actual-app/api (no subprocess spawning per command).

  • In-memory caching for accounts, categories, category groups, payees, and tags.

  • Process-level SQLite corruption self-healing and PID-isolated instance data directories.

  • Automatic Schema Mismatch detection & package auto-upgrades (@actual-app/api and @actual-app/cli).

• Comprehensive Budget Toolset:

  • Full query engine using ActualQL (actual_query) with filters, order-by, grouping, pagination, and count.

  • Full CRUD operations for accounts, transactions (including split transactions), categories, category groups, payees, tags, rules, and schedules.

  • Dynamic skill documentation resource (actual://skill-docs) and system prompt guidance.

Related MCP server: actual-mcp-server

Architecture

flowchart TD
    subgraph Clients ["AI Clients & Agents"]
        Claude["Claude Desktop / Cursor<br/>(Stdio Transport)"]
        Remote["Remote Agents / Webhooks<br/>(Streamable HTTP + OAuth2)"]
    end

    subgraph Server ["Actual Budget MCP Server"]
        Router["Express Router & Transport Layer"]
        Auth["OAuth2 & Session Engine<br/>(SQLite auth.sqlite)"]
        Tools["MCP Tool Registry<br/>(Query, Transactions, Accounts, etc.)"]
        Cache["In-Memory Cache & Self-Healing Engine"]
    end

    subgraph ActualCore ["Actual Budget Core"]
        API["@actual-app/api"]
        Instance["Isolated Instance DB<br/>(~/.actual-data/:pid)"]
        Sync["Actual Budget Server<br/>(Local or Remote)"]
    end

    Claude -->|stdin/stdout| Tools
    Remote -->|HTTPS Bearer Token| Router
    Router --> Auth
    Auth --> Tools
    Tools --> Cache
    Cache --> API
    API --> Instance
    API -->|CRDT Sync| Sync

OAuth2 Authentication & Session Flow

sequenceDiagram
    autonumber
    actor Agent as AI Client / Agent
    participant MCP as Actual MCP Server
    participant SQLite as Token DB (auth.sqlite)
    participant Core as Actual Budget API

    Agent->>MCP: GET /.well-known/oauth-protected-resource
    MCP-->>Agent: 200 OK (Auth Server & Scopes)
    Agent->>MCP: GET /oauth/authorize?client_id=...&code_challenge=...
    MCP->>Agent: 302 Redirect to callback with authorization code
    Agent->>MCP: POST /oauth/token (Exchange code + PKCE verifier)
    MCP->>SQLite: Persist Access & Refresh Tokens
    MCP-->>Agent: 200 OK (access_token, refresh_token, expires_in)
    Agent->>MCP: POST /mcp (Header: Authorization: Bearer <token>)
    MCP->>SQLite: Validate Token & Scope
    MCP->>Core: Execute Budget Query / Action
    Core-->>MCP: Results
    MCP-->>Agent: JSON-RPC 2.0 Response

Getting Started

Prerequisites

• Node.js: v20.0.0 or higher

• An Actual Budget server instance (self-hosted or hosted)

Installation

git clone https://github.com/your-username/actual-mcp.git
cd actual-mcp
npm install

Configuration

You can configure actual-mcp using environment variables (via a .env file or exported in your shell) or via ~/.actualrc.json.

Copy the example environment template:

cp .env.example .env

Environment Variables

Configuration via ~/.actualrc.json

If environment variables are not set, actual-mcp automatically reads connection details from ~/.actualrc.json:

{
  "serverUrl": "http://localhost:5006",
  "password": "your_server_password",
  "syncId": "your_sync_id",
  "encryptionPassword": "your_encryption_password"
}

Usage

1. Stdio Mode (Claude Desktop / Cursor)

Add the server to your claude_desktop_config.json:

{
  "mcpServers": {
    "actual": {
      "command": "node",
      "args": [
        "/path/to/actual-mcp/index.js"
      ],
      "env": {
        "ACTUAL_SERVER_URL": "http://localhost:5006",
        "ACTUAL_PASSWORD": "your_server_password",
        "ACTUAL_SYNC_ID": "your_sync_id",
        "ACTUAL_ENCRYPTION_PASSWORD": "your_encryption_password"
      }
    }
  }
}

2. Streamable HTTP Mode (Standalone Server)

Start the HTTP server on port 3000:

# With OAuth2 authentication enabled (requires OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET):
node index.js --port 3000

# With OAuth2 authentication disabled (trusted local network):
node index.js --port 3000 --no-auth

Once running:

• MCP Endpoint: http://localhost:3000/mcp

• Health Check: http://localhost:3000/health

• OAuth Discovery: http://localhost:3000/.well-known/oauth-authorization-server

• OAuth Protected Resource Metadata: http://localhost:3000/.well-known/oauth-protected-resource

3. Cleanup Stale Processes

If previous instances crashed or left zombie processes:

npm run cleanup

Tool Reference

License

This project is licensed under the MIT License.