agigante80/actual-mcp-server

Talk to your self-hosted Actual Budget from any MCP client: a remote HTTP server for LibreChat/LobeChat or a local stdio process for Claude Desktop, with 71 tools for transactions, budgets, rules, and bank sync. No Docker needed for local use.

41 ★14 forksJavaScriptUpdated 22d ago

What you need to know

Production-grade MCP server connecting any MCP-compatible assistant to a self-hosted Actual Budget instance. 74 tools covering accounts, transactions (including exclusive ActualQL-powered search), categories, payees, tags, rules, budgets, schedules, bank sync and batch operations. Supports HTTP (Streamable HTTP with Bearer/OIDC auth) and stdio transports, multi-budget switching and multi-user ACLs.

Install

docker run -d --name actual-mcp-server-backend -p 3600:3600 -e ACTUAL_SERVER_URL=... -e ACTUAL_PASSWORD=... -e ACTUAL_BUDGET_SYNC_ID=... ghcr.io/agigante80/actual-mcp-server:latest
npx actual-mcp-server --http (Node.js 22+)
npm run build && npm run dev -- --http (from clone)
stdio: add to claude_desktop_config.json with npx -y actual-mcp-server --stdio

Usage

•Ask natural-language questions about budget, create transactions, analyze spending
•actual_budgets_switch to change active budget mid-conversation
•Use actual_query_run for custom ActualQL queries and actual_bank_sync to trigger GoCardless/SimpleFIN sync

Key features

✓74 tools with actual_<category>_<action> naming
✓6 exclusive ActualQL-powered transaction search/summary tools
✓HTTP and stdio transports with per-session budget scoping
✓Multi-budget switching at runtime (BUDGET_N_* env vars)
✓OIDC auth with JWKS-validated JWTs and per-user budget ACLs
✓Connection pooling, retry with exponential backoff, full test suite
✓Split transactions, transfer tool, batch operations, budget import/export

Best for

Self-hosted Actual Budget users who want AI access to their budget with production reliability

Caveats

⚠Requires an Actual Budget server, ACTUAL_SERVER_URL, ACTUAL_PASSWORD and budget Sync ID
⚠Requires a persistent data dir volume (MCP_BRIDGE_DATA_DIR or /app/data) for the local budget copy
⚠Not affiliated with Actual Budget; user assumes responsibility for financial data
⚠HTTP mode should use a strong Bearer token or OIDC

Platforms: Windows · macOS · LinuxClients: Claude Desktop · Cursor · VS Code · Gemini CLI · Claude Code · LibreChat · LobeChat

Documentation ↗

Reviewed 2026-08-11

Topics

actual-budgetai-assistantapi-serverbudget-managementbudget-trackingconversation-aidockerfinance-automationfinancial-managementlibrechatmcpmodel-context-protocolnodejs personal-financetypescript

Stars: 41★
Forks: 14
Language: JavaScript
License: MIT
Created: 2025-10-02
Last push: 2026-08-13