Talk to your budget. Run it anywhere. Trust it in production.
Production-grade Model Context Protocol server that connects LibreChat, LobeChat, and Claude Desktop directly to your self-hosted Actual Budget. 63 tools, two transports, multi-budget switching at runtime.
npx command and you are done.Most existing Actual Budget MCP servers were built as simple stdio bridges for single-user Claude Desktop sessions. They work fine on a developer laptop. They fall apart the moment you want a remote server for LibreChat or LobeChat, multi-user authentication, multiple budget files, or a real test suite covering more than the happy path.
Personal finance is an unforgiving domain. A misrouted transaction or a deleted category cascades through months of data. Operators need production tools, not toys.
HTTP (--http) for remote clients like LibreChat. Stdio (--stdio) for local Claude Desktop. Same 63 tools either way. Most alternatives pick one.
Search transactions by month, amount, category, or payee. Aggregated summaries instead of dumping raw rows into the AI context window. Token-efficient and unique to this server.
Configure N budget files. The AI calls actual_budgets_switch mid-conversation. Personal becomes Family becomes Business without restarting anything.
Connection pooling (up to 15 concurrent sessions), exponential-backoff retry, full test suite (unit + E2E + integration). The plumbing nobody talks about until it breaks.
JWKS-validated JWTs, AUTH_BUDGET_ACL for per-user budget scoping. Casdoor-tested. The only Actual MCP with real multi-tenancy.
Each AI client speaks MCP over its preferred transport. The server normalises both into the same internal tool dispatcher, which wraps every Actual Budget API call in a retry-and-pool layer before touching the local SQLite copy.
┌─────────────┐ MCP/HTTP ┌──────────────────┐ Actual API ┌──────────────┐
│ LibreChat │ ◄────────────► │ Actual MCP │ ◄────────────► │ Actual │
│ LobeChat │ │ Server │ │ Budget │
│ (remote) │ │ (63 tools) │ │ Server │
└─────────────┘ └──────────────────┘ └──────────────┘
▲
┌─────────────┐ MCP/stdio │
│ Claude │ ◄──────────────────────►│
│ Desktop │ │
│ (local) │ │
└─────────────┘ │
▼
retry + pool + ACL + SQLite mirrorEvery Actual API call goes through withActualApi() in src/lib/actual-adapter.ts, which handles init / shutdown lifecycle, retry (3 attempts, exponential backoff), and concurrency limiting.
The MCP spec lets you ship one do_anything tool with a free-form prompt. I built 63 narrow tools instead, one per Actual operation, each with strict Zod-validated inputs. AI models route to the right tool more reliably; bad inputs fail at the schema, not after touching the database.
stdio is easier and most Actual MCPs stop there. But LibreChat and LobeChat are HTTP-native; forcing them through mcp-remote adds latency and an extra failure surface. Two transports doubles the test matrix but unlocks the production use case.
Actual Budget has no REST API. The official library downloads a local copy of your budget and syncs writes back. The server has to persist that copy or it re-downloads on every restart. Documented as a hard requirement in the Quick Start; misreading it is the number-one cause of failed first-time setups.
# Pull and run with your Actual Budget credentials.
docker run -d --name actual-mcp-server-backend \
-p 3600:3600 \
-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_token \
-v actual-mcp-data:/data \
ghcr.io/agigante80/actual-mcp-server:latest
# Verify
curl http://localhost:3600/health
# No Docker, no HTTP server. Drop into claude_desktop_config.json:
{
"mcpServers": {
"actual-budget": {
"command": "npx",
"args": ["-y", "actual-mcp-server", "--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/data-dir"
}
}
}
}
→ Full setup guide configuration, deployment, troubleshooting
Snapshot: 2026-03-20. Versions and feature flags reflect each project at that date.
| Feature | Actual MCP Server | s-stefanov/actual-mcp | henfrydls/actual-budget-mcp | WGDev/ynab-mcp |
|---|---|---|---|---|
| Version | v0.6.14 | v1.11.1 | v0.2.0 | v0.1.0 |
| Tool count | 63 | ~22 | 18 | 9 |
| Setup and distribution | ||||
| Transport | HTTP + stdio | stdio + SSE | stdio | stdio |
| Docker support | ✓ Full (image + Compose) | ~ Image only | ✗ | ✗ |
| Published package | ✓ npm | ✓ npm | ✓ npm | ✓ pip |
| Security and access | ||||
| Authentication | ✓ Bearer + OIDC | ~ Optional Bearer | ✗ None | ✓ Keyring |
| Multi-budget switching | ✓ Runtime via tool | ✗ | ✗ | ✓ (YNAB native) |
| Production and reliability | ||||
| Connection pooling | ✓ Up to 15 sessions | ✗ | ✗ | ✗ |
| Retry and backoff | ✓ 3 attempts, exponential | ✗ | ✗ | ✗ |
| Automated test suite | ✓ Unit + E2E + integration | ✗ | ✗ | ✗ |
| Analysis and reporting | ||||
| ActualQL custom queries | ✓ 6 exclusive tools | ✗ | ✗ | N/A |
| Bank sync | ✓ GoCardless / SimpleFIN | ✗ | ✓ | N/A |
When to choose another: s-stefanov for built-in read-only mode. henfrydls for Spanish UI and natural-language dates. ynab-mcp if you are on YNAB instead of Actual.