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   ┌──────────────┐
│  LibreChat  │ ◄───────────► │  Actual MCP      │ ◄───────────► │   Actual     │
│  LobeChat   │               │  Server          │               │   Budget     │
│  (remote)   │               │  (63 tools)      │               │   Server     │
└─────────────┘               └──────────────────┘               └──────────────┘

┌─────────────┐   MCP/stdio   ┌──────────────────┐   Actual API   ┌──────────────┐
│  Claude     │ ◄───────────► │  Actual MCP      │ ◄───────────► │   Actual     │
│  Desktop    │               │  Server          │               │   Budget     │
│  (local)    │               │  (63 tools)      │               │   Server     │
└─────────────┘               └──────────────────┘               └──────────────┘

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 and stdio transport. Runs as a real remote server for LibreChat/LobeChat (--http), or as a direct local process for Claude Desktop (--stdio) — no Docker or HTTP server needed for local use.
• 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 63 tools tested end-to-end. Any MCP-compatible client should work.

---

Table of Contents

• Quick Start
• Upgrading
• 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 (HTTP server)

# 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

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

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 63 tools are available.

MCP_BRIDGE_DATA_DIR should be an absolute path — without it, the data directory resolves relative to wherever the client spawns the process, which can be unpredictable. The directory is created automatically on first run.

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 via HTTP (when the server is already running as a Docker container):

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

Claude Desktop via stdio (native, no HTTP server needed — see Option D above):

{
  "mcpServers": {
    "actual-budget": {
      "command": "node",
      "args": ["/absolute/path/to/actual-mcp-server/dist/src/index.js", "--stdio"],
      "env": {
        "ACTUAL_SERVER_URL": "http://localhost:5006",
        "ACTUAL_PASSWORD": "your_password",
        "ACTUAL_BUDGET_SYNC_ID": "your-sync-id",
        "MCP_BRIDGE_DATA_DIR": "/absolute/path/to/actual-mcp-server/actual-data"
      }
    }
  }
}

See docs/guides/MCP_CLIENTS_SETUP.md for all options (including Cursor, VS Code, Gemini CLI), Linux/NVM path fixes, and troubleshooting.

---

Upgrading

Docker (Option A)

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

npm / cloned repo (Option C)

git pull
npm install
npm run build
# Then restart the server

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 — you must upgrade it explicitly:

# 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.

---

Available Tools

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

Accounts (7)

Tool	Description
actual_accounts_list	List all accounts
actual_accounts_create	Create new account
actual_accounts_update	Update account details
actual_accounts_delete	Permanently delete account
actual_accounts_close	Close account (soft delete)
actual_accounts_reopen	Reopen closed account
actual_accounts_get_balance	Get account balance at a date

Transactions (13)

Standard (6)

Tool	Description
actual_transactions_get	Get transactions for an account
actual_transactions_filter	Filter with advanced criteria
actual_transactions_create	Create new transaction(s)
actual_transactions_import	Import and reconcile transactions
actual_transactions_update	Update a transaction
actual_transactions_delete	Delete a transaction

Utility (1)

Tool	Description
actual_transactions_uncategorized	Summary of uncategorized transactions (totalCount, totalAmount, per-account breakdown); pass includeTransactions:true for paginated rows

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

Tool	Description
actual_transactions_search_by_month	Search by month using $month transform
actual_transactions_search_by_amount	Find by amount range
actual_transactions_search_by_category	Search by category name
actual_transactions_search_by_payee	Find by payee/vendor
actual_transactions_summary_by_category	Spending summary grouped by category
actual_transactions_summary_by_payee	Top vendors with totals and counts

Transfers (1)

Tool	Description
actual_transfers_create	Create a paired transfer between two accounts (debit + credit linked by transfer_id, identical to UI "Make Transfer")

How transfers work under the hood — Actual Budget requires the runTransfers: true option when adding transactions so that both sides (the debit on the source account and the credit on the destination account) are created and linked via a shared transfer_id. Prior to v0.5.6, the adapter forwarded a hardcoded empty options object {} to rawAddTransactions, silently dropping any options including this flag. This meant that calling actual_transfers_create would appear to succeed but only one side of the transfer would be recorded. The fix ensures options are forwarded correctly; use actual_transfers_create (not actual_transactions_create) for all account-to-account moves.

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)

Tool	Description
actual_budgets_list_available	List all configured budget files
actual_budgets_switch	Switch active budget (multi-budget)
actual_budgets_get_all	List available budget files
actual_budgets_getMonths	List budget months
actual_budgets_getMonth	Get budget for a specific month
actual_budgets_setAmount	Set category budget amount
actual_budgets_transfer	Transfer amount between categories
actual_budgets_setCarryover	Enable/disable carryover
actual_budgets_holdForNextMonth	Hold funds for next month
actual_budgets_resetHold	Reset hold status

Rules (4)

actual_rules_get · actual_rules_create · actual_rules_update · actual_rules_delete

Advanced Query & Sync (2)

Tool	Description
actual_query_run	Execute custom ActualQL query
actual_bank_sync	Trigger bank sync (GoCardless/SimpleFIN)

Batch Operations (1)

actual_budget_updates_batch — batch multiple budget updates in one call

Server Information & Lookup (3)

Tool	Description
actual_server_info	Server status, version, build info
actual_server_get_version	Actual Budget server version
actual_get_id_by_name	Resolve name → UUID for accounts, categories, payees

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

Variable	Default	Required	Description
Actual Budget Connection
ACTUAL_SERVER_URL	http://localhost:5006	Yes	URL of your Actual Budget server. Use the same URL you type in your browser: http://localhost:5006 (local), http://192.168.1.x:5006 (network), https://actual.yourdomain.com (domain), or http://actual:5006 (container name if on the same Docker network)
ACTUAL_PASSWORD	—	Yes	Password for Actual Budget server
ACTUAL_BUDGET_SYNC_ID	—	Yes	Budget Sync ID from Actual (Settings → Sync ID)
ACTUAL_BUDGET_PASSWORD	—	No	Optional encryption password for encrypted budgets
MCP Server Settings
MCP_BRIDGE_PORT	3000 (dev) / 3600 (Docker)	No	Port for MCP server to listen on
MCP_BRIDGE_BIND_HOST	0.0.0.0	No	Host address to bind server to (0.0.0.0 = all interfaces)
MCP_BRIDGE_DATA_DIR	./actual-data	No	Directory to store Actual Budget local data (SQLite). Required to be a persistent path. The @actual-app/api library downloads a local copy of your budget here to run queries — use a volume mount in Docker to persist it across restarts
MCP_BRIDGE_PUBLIC_HOST	auto-detected	No	Public hostname/IP for server (shown in logs)
MCP_BRIDGE_PUBLIC_SCHEME	auto-detected	No	Public scheme (http or https)
MCP_BRIDGE_USE_TLS	false	No	Set to true to advertise https:// in the server URL (for reverse-proxy setups where TLS is terminated upstream)
Transport Configuration
MCP_TRANSPORT_MODE	--http	No	Transport mode: --http or --stdio
MCP_HTTP_PATH	/http	No	HTTP endpoint routing path
MCP_BRIDGE_HTTP_PATH	same as MCP_HTTP_PATH	No	Advertised HTTP path shown to clients (set when a reverse proxy rewrites the path)
Session Management
USE_CONNECTION_POOL	true	No	Enable session-based connection pooling
MAX_CONCURRENT_SESSIONS	15	No	Maximum concurrent MCP sessions allowed
SESSION_IDLE_TIMEOUT_MINUTES	5 (pool) / 2 (HTTP)	No	Minutes before idle session cleanup
Security & Authentication
AUTH_PROVIDER	none	No	Auth mode: none (static Bearer) or oidc (JWKS-validated JWT)
MCP_SSE_AUTHORIZATION	—	No	Static Bearer token (AUTH_PROVIDER=none; highly recommended in production)
OIDC_ISSUER	—	If OIDC	OIDC issuer URL (e.g., https://sso.example.com)
OIDC_RESOURCE	—	No	Expected aud claim in JWT (your client ID)
OIDC_SCOPES	—	No	Comma-separated required scopes; leave empty for Casdoor
AUTH_BUDGET_ACL	—	No	Per-user budget ACL — see AI Client Setup
MCP_ENABLE_HTTPS	false	No	Enable native TLS. Requires MCP_HTTPS_CERT and MCP_HTTPS_KEY
MCP_HTTPS_CERT	—	No	Path to PEM certificate file (required when MCP_ENABLE_HTTPS=true)
MCP_HTTPS_KEY	—	No	Path to PEM private key file (required when MCP_ENABLE_HTTPS=true)
Logging Configuration
MCP_BRIDGE_STORE_LOGS	false	No	Enable file logging (vs console only)
MCP_BRIDGE_LOG_DIR	./logs	No	Directory for log files (if STORE_LOGS=true)
MCP_BRIDGE_LOG_LEVEL	debug	No	Log level: error, warn, info, debug
Log Rotation (when MCP_BRIDGE_STORE_LOGS=true)
MCP_BRIDGE_MAX_FILES	14d	No	Keep rotated logs for N days (e.g., 14d, 30d)
MCP_BRIDGE_MAX_LOG_SIZE	20m	No	Rotate when file reaches size (e.g., 20m, 100m)
MCP_BRIDGE_ROTATE_DATEPATTERN	YYYY-MM-DD	No	Date pattern for rotated log filenames
Development & Debugging
DEBUG	false	No	Enable debug mode (verbose logging)
LOG_LEVEL	info	No	Log level override: error, warn, info, debug
MCP_BRIDGE_DEBUG_TRANSPORT	false	No	Enable transport-level debug logging
Advanced/Internal
ACTUAL_API_CONCURRENCY	5	No	Max concurrent Actual API operations
NODE_ENV	production	No	Node environment; production hides stack traces in error responses
VERSION	auto-detected	No	Server version (auto-set by build/Docker)
TZ	UTC	No	Timezone for timestamps (e.g., America/New_York)

---

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.

Variable	Required	Fallback
BUDGET_DEFAULT_NAME	No	"Default"
BUDGET_N_NAME	Yes (enables group)	—
BUDGET_N_SYNC_ID	Yes	—
BUDGET_N_SERVER_URL	No	ACTUAL_SERVER_URL
BUDGET_N_PASSWORD	No	ACTUAL_PASSWORD
BUDGET_N_ENCRYPTION_PASSWORD	No	—

# 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 supports two transport modes:

Mode	Flag	Use case	Auth
HTTP	--http	LibreChat, LobeChat, Docker, multi-user deployments	Bearer token or OIDC
stdio	--stdio	Claude Desktop, Cursor, local single-user use	None (OS process isolation)

The two modes are mutually exclusive — pass exactly one flag when starting the server.

stdio transport

stdio is the simplest way to connect Claude Desktop directly to Actual Budget. The MCP server runs as a child process; Claude Desktop spawns it, communicates over stdin/stdout using NDJSON (the MCP wire format), and the process exits cleanly when Claude Desktop closes.

Key properties of stdio mode:

• No network port — the transport is a pipe, not a socket
• No auth token — process ownership is the security boundary
• All logs go to stderr so they never corrupt the JSON-RPC framing on stdout
• The process exits when stdin closes (Claude Desktop shutting down)
• All 63 tools are available, identical to HTTP mode

Start manually to verify:

cd /path/to/actual-mcp-server
ACTUAL_SERVER_URL=http://localhost:5006 \
ACTUAL_PASSWORD=your_password \
ACTUAL_BUDGET_SYNC_ID=your-sync-id \
node dist/src/index.js --stdio

Send a test request (keep stdin open with sleep):

{ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'; sleep 5; } \
| ACTUAL_SERVER_URL=http://localhost:5006 ACTUAL_PASSWORD=your_password ACTUAL_BUDGET_SYNC_ID=your-sync-id \
  node dist/src/index.js --stdio 2>/dev/null

Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "actual-budget": {
      "command": "node",
      "args": ["/absolute/path/to/actual-mcp-server/dist/src/index.js", "--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/actual-mcp-server/actual-data"
      }
    }
  }
}

Path must be absolute. Claude Desktop does not inherit shell PATH, so node must also be absolute if you use NVM or a non-standard install: /home/youruser/.nvm/versions/node/v22.x.x/bin/node.

See docs/guides/MCP_CLIENTS_SETUP.md for all connection options (stdio native, mcp-remote via HTTP/HTTPS), other clients (Cursor, VS Code, Gemini CLI, Claude Code), Linux path fixes, and troubleshooting.

HTTP transport

HTTP transport uses the /http endpoint (StreamableHTTP) with optional Bearer token or OIDC 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

Command	What It Tests	Requires Live Server
npm run build	TypeScript compilation	No
npm run test:unit-js	63-tool smoke, schema validation, auth ACL	No
npm run test:adapter	Adapter, retry logic, concurrency	No
npm run test:e2e	MCP protocol compliance (Playwright)	No
npm run test:e2e:docker:full	Full stack integration	Yes (Docker)
npm run test:integration	Live server sanity checks	Yes
npm run test:integration:full	Full live integration suite	Yes

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

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

---

Documentation

Document	Contents
docs/guides/MCP_CLIENTS_SETUP.md	Start here — connect Claude Desktop, Cursor, VS Code (Copilot), Gemini CLI, or Claude Code
docs/guides/AI_CLIENT_SETUP.md	LibreChat & LobeChat setup, Docker networking, HTTPS/TLS proxy, OIDC
docs/guides/DEPLOYMENT.md	Docker, Docker Compose profiles, production config, Kubernetes
docs/ARCHITECTURE.md	Component layers, data flow, transport protocols
docs/SECURITY_AND_PRIVACY.md	Auth models, threat model, hardening
docs/TESTING_AND_RELIABILITY.md	Test strategy, coverage, reliability patterns
docs/NEW_TOOL_CHECKLIST.md	Step-by-step guide for adding a new MCP tool
CONTRIBUTING.md	Development setup, code standards, PR process
.env.example	Fully annotated environment variable reference

---

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

Feature	agigante80/actual-mcp-server	s-stefanov/actual-mcp	henfrydls/actual-budget-mcp	WGDevelopment/ynab-mcp-server
Version	v0.4.26	v1.11.1	v0.2.0	v0.1.0
Budget App	Actual Budget (self-hosted)	Actual Budget (self-hosted)	Actual Budget (self-hosted)	YNAB (cloud, subscription)
Language	TypeScript / Node.js	TypeScript / Node.js	TypeScript / Node.js	Python
Tool Count	63	~22	18	9
— Setup & Distribution —
Transport	HTTP + stdio	STDIO + SSE option	STDIO	STDIO
Docker support	✅ Full (image + Compose)	✅ Image only	❌	❌
Published package (npx/pip)	✅ npx actual-mcp-server	✅ npx actual-mcp	✅ npx actual-budget-mcp	✅ pip install ynab-mcp
— Security & Access —
Authentication	✅ Bearer token + OIDC (JWKS)	⚠️ Optional Bearer token	❌ None (local only)	✅ OS keyring / env var
Read-only mode	❌ All tools always available	✅ Write requires --enable-write flag	❌	✅ Most tools are read-only
Multi-budget switching	✅ Runtime switch via tool	❌	❌	✅ (YNAB natively multi-budget)
— Production & Reliability —
Connection pooling	✅ Up to 15 concurrent sessions	❌	❌	❌
Retry / backoff	✅ 3 attempts, exponential backoff	❌	❌	❌
Automated test suite	✅ Unit + E2E + integration	❌	❌	❌
— Transactions —
Create / update / delete	✅	✅	✅	✅
Import & reconcile	✅ actual_transactions_import	❌	❌	❌
Scheduled / recurring	❌ (planned)	❌	❌	❌
— Analysis & Reporting —
ActualQL custom queries	✅ 6 exclusive tools + actual_query_run	❌	❌	N/A
Summary by category / payee	✅	✅ spending-by-category	✅	❌
Spending projections / forecast	❌	❌	✅ end-of-month forecast	❌
Budget vs actual comparison	✅ via actual_budgets_getMonth	❌	✅ dedicated tool	✅ month summary
Bank sync	✅ GoCardless / SimpleFIN	❌	✅	❌ (YNAB handles sync natively)
— Budget Management —
Set / transfer / carryover / hold	✅ Full (10 tools)	❌	✅ Partial	✅ Partial
Batch budget updates	✅ actual_budget_updates_batch	❌	❌	❌
— Accounts, Payees & Rules —
Account lifecycle (close/reopen)	✅	❌	❌	N/A
Payee merging	✅ actual_payees_merge	❌	❌	N/A
Payee rules management	✅ Full CRUD	✅ Full CRUD	❌	N/A
— UX & Usability —
Natural language date parsing	❌ YYYY-MM-DD required	❌	✅ "last month", "yesterday"	❌
Bilingual support	❌	❌	✅ English + Spanish	❌
Auto name → UUID resolution	⚠️ Explicit tool (actual_get_id_by_name)	❌	✅ Automatic in all tools	❌
AI prompt templates	❌	✅ financial-insights, budget-review	❌	❌
Tested AI clients	LibreChat, LobeChat	Claude Desktop, Codex	Claude Desktop, Cursor, VS Code	Claude Code
License	MIT	MIT	MIT	MIT

When to choose which project

• This project — best for production deployments, multi-user environments (OIDC), LibreChat/LobeChat, Docker-native setup, or for Claude Desktop users who want a native stdio connection without any HTTP server overhead.
• 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)
• Transports: Express + StreamableHTTP (--http) · StdioServerTransport (--stdio)
• Logging: Winston with daily rotation (all output routed to stderr in stdio mode)

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.6.6 | Tool Count: 63 (verified LibreChat-compatible)