Actual MCP Server

Talk to your budget. Run it anywhere. Trust it in production.

Actual MCP Server is a Model Context Protocol server that connects any MCP-compatible AI assistant — LibreChat, LobeChat, Claude Desktop, and more — directly to your self-hosted Actual Budget instance. Ask natural language questions, create transactions, analyse spending, and manage your entire budget without ever opening the Actual Budget UI.

┌─────────────┐   MCP/HTTP   ┌──────────────────┐   Actual API   ┌──────────────┐
│  AI Client  │ ◄──────────► │  Actual MCP      │ ◄───────────► │   Actual     │
│ (LibreChat, │              │  Server          │               │   Budget     │
│  LobeChat,  │              │  (62 tools)      │               │   Server     │
│  Claude     │              └──────────────────┘               └──────────────┘
│  Desktop…)  │
└─────────────┘

Why this project?

Most Actual Budget MCP implementations are simple stdio bridges designed for single-user, local use with Claude Desktop. This project goes further:

• 62 tools — the most comprehensive coverage available. Accounts, transactions, categories, payees, rules, budgets, batch operations, bank sync, and more. Covers 84% of the Actual Budget API.
• HTTP transport, not stdio. Runs as a real remote server accessible by any number of clients simultaneously — essential for LibreChat, LobeChat, or any web-based AI assistant.
• 6 exclusive ActualQL-powered tools. Search and summarise transactions by month, amount, category, or payee using Actual Budget's native query engine. Aggregated results, no raw data dumped into the AI context window.
• Multi-budget switching at runtime. Configure multiple budget files and let the AI switch between them mid-conversation with actual_budgets_switch.
• Multi-user ready with OIDC. Secure every session with JWKS-validated JWTs and per-user budget ACLs — no shared tokens required.
• Production-grade reliability. Connection pooling (up to 15 concurrent sessions), automatic retry with exponential backoff, and a full test suite (unit + E2E + integration).

Verified working with LibreChat, LobeChat, and Claude Desktop. All 62 tools tested end-to-end. Any MCP-compatible client should work.

Table of Contents

• Quick Start
• Available Tools
• Configuration
• Multi-Budget Switching
• Transport & Authentication
• Testing
• Documentation
• Comparison with Similar Projects
• Contributing
• License
• Disclaimer

Quick Start

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:/data \        # required — see note below
  -v actual-mcp-logs:/app/logs \
  ghcr.io/agigante80/actual-mcp-server:latest

Why the /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 /data volume gives the container a persistent, writable place to store that local copy. 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:

# Quick health check
curl http://localhost:3600/health
# Expected: {"status":"ok","transport":"http","version":"..."}

# Full MCP handshake (also verifies your token)
curl -s -X POST http://localhost:3600/http \
  -H "Authorization: Bearer your_secret_token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"cli-test","version":"1.0"}}}' \
  | python3 -m json.tool
# Success: JSON response with "protocolVersion" and "serverInfo"
# Wrong token: {"error": "Unauthorized"}
# Server not running: curl: (7) Failed to connect

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

Option B — Docker Compose

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   # Nginx proxy on :3600
# or
docker compose --profile dev up -d          # dev mode with hot-reload
# or
docker compose --profile fullstack up -d    # includes Actual Budget server on :5006

Option C — npm

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:3000/http (dev) or http://localhost:3600/http (Docker).

Connect an AI client

LibreChat / LobeChat — add to librechat.yaml (or LobeChat MCP plugin settings):

mcpServers:
  actual-mcp:
    type: "streamable-http"
    url: "http://actual-mcp-server-backend:3600/http"
    headers:
      Authorization: "Bearer YOUR_TOKEN_HERE"
    serverInstructions: true
    timeout: 600000

See docs/guides/AI_CLIENT_SETUP.md for full LibreChat, LobeChat, network, and HTTPS/TLS proxy setup.

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "actual-budget": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3600/http",
        "--header",
        "Authorization: Bearer YOUR_TOKEN_HERE"
      ]
    }
  }
}

See docs/guides/CLAUDE_DESKTOP_SETUP.md for HTTPS setup, Linux/NVM fixes, and troubleshooting.

Available Tools

62 tools across 12 categories. All tools use the actual_<category>_<action> naming convention.

Accounts (7)

Transactions (12)

Standard (6)

Exclusive ActualQL-powered (6) — unique to this MCP server

Categories (4)

actual_categories_get · actual_categories_create · actual_categories_update · actual_categories_delete

Category Groups (4)

actual_category_groups_get · actual_category_groups_create · actual_category_groups_update · actual_category_groups_delete

Payees (6)

actual_payees_get · actual_payees_create · actual_payees_update · actual_payees_delete · actual_payees_merge · actual_payee_rules_get

Budgets (10)

Rules (4)

actual_rules_get · actual_rules_create · actual_rules_update · actual_rules_delete

Advanced Query & Sync (2)

Batch Operations (1)

actual_budget_updates_batch — batch multiple budget updates in one call

Server Information & Lookup (3)

Session Management (2)

actual_session_list · actual_session_close

Not Yet Implemented

• Scheduled/recurring transactions (getSchedules, createSchedule, updateSchedule, deleteSchedule)

Configuration

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

Complete Environment Variables Reference

Multi-Budget Switching

Configure multiple Actual Budget files so the AI can switch between them at runtime using actual_budgets_list_available and actual_budgets_switch.

BUDGET_N_SERVER_URL and BUDGET_N_PASSWORD fall back to ACTUAL_SERVER_URL / ACTUAL_PASSWORD when omitted.

# Default budget
ACTUAL_SERVER_URL=http://actual:5006
ACTUAL_PASSWORD=my-password
ACTUAL_BUDGET_SYNC_ID=aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa
BUDGET_DEFAULT_NAME=Personal

# Budget 1 — same server, same password
BUDGET_1_NAME=Family
BUDGET_1_SYNC_ID=bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb

# Budget 2 — different server
BUDGET_2_NAME=Business
BUDGET_2_SERVER_URL=https://actual-office.example.com
BUDGET_2_PASSWORD=office-password
BUDGET_2_SYNC_ID=cccccccc-cccc-cccc-cccc-cccccccccccc

Transport & Authentication

The server uses HTTP transport (/http endpoint) with optional Bearer token authentication.

Static Bearer token (single-user)

# Generate a token
openssl rand -hex 32

# Add to .env
MCP_SSE_AUTHORIZATION=your_token_here

Clients send: Authorization: Bearer your_token_here

OIDC (multi-user)

AUTH_PROVIDER=oidc
OIDC_ISSUER=https://sso.yourdomain.com
OIDC_RESOURCE=your-client-id    # must match 'aud' JWT claim
OIDC_SCOPES=                    # leave empty for Casdoor

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

Testing

Integration test levels (tests/manual/): sanity → smoke → normal → extended → full → cleanup

See tests/manual/README.md and tests/e2e/README.md for details.

Documentation

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

When to choose which project

• This project — best for production deployments, multi-user environments (OIDC), LibreChat/LobeChat, or when you need the broadest tool coverage and Docker-native setup.
• s-stefanov/actual-mcp — the original implementation; good for Claude Desktop with STDIO transport, AI-generated prompt templates, and built-in read-only mode.
• henfrydls/actual-budget-mcp — best for Spanish-speaking users, Cursor/VS Code integration, or when you want natural-language dates, automatic name resolution, and spending forecasts without any server setup.
• WGDevelopment/ynab-mcp-server — only option if you're a YNAB user; privacy-first design with OS keyring token storage and local-LLM focus.

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup, code standards, and the PR process.

Quick flow:

1. Fork → git checkout -b feature/my-feature
2. Make changes + add tests
3. npm run build && npm run test:unit-js must pass
4. Open a Pull Request

Architecture

• Runtime: Node.js 22 (Alpine Linux in Docker)
• Language: TypeScript 5.9 (ESM, NodeNext module resolution)
• MCP SDK: @modelcontextprotocol/sdk ^1.25.2
• Actual API: @actual-app/api ^26.3.0
• Validation: Zod (runtime types + JSON Schema for tool inputs)
• Transport: Express (HTTP)
• Logging: Winston with daily rotation

Every Actual API call goes through the withActualApi() wrapper in src/lib/actual-adapter.ts, which handles init/shutdown lifecycle, retry (3 attempts, exponential backoff), and concurrency limiting. See docs/ARCHITECTURE.md for full design documentation.

License

MIT — see LICENSE for details.

Acknowledgments

• Actual Budget — open-source budgeting software
• Model Context Protocol — standardised AI-app integration
• LibreChat — open-source ChatGPT alternative
• s-stefanov/actual-mcp — original adapter pattern

Disclaimer

This project started as a personal learning exercise to explore the Model Context Protocol technology. It is an independent open-source project, not affiliated with, endorsed by, or supported by Actual Budget or any other organisation.

The software is provided as-is, without warranty of any kind. The author accepts no responsibility for how it is used, for any data loss, financial errors, or other consequences arising from its use. If you connect it to real financial data, you do so entirely at your own risk.

Support

• GitHub Issues — bug reports and feature requests
• GitHub Discussions — questions and ideas

Version: 0.4.33 | Tool Count: 62 (verified LibreChat-compatible)