# Actual Budget MCP Server Gives an AI assistant access to your Actual Budget data: accounts, transactions, categories and reports, all through plain-language requests. - MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 268 - Author: s-stefanov - License: MIT · policy=link-only · description only; the file stays with the author - Source: https://github.com/s-stefanov/actual-mcp - Updated: 2026-10-23 - HTML: https://affpapa.org/en/nevibecode/mcp/actual-budget-mcp-server ## What it does The server hands your assistant the contents of an Actual Budget file: accounts with balances, transaction history, categories, payees and rules. A second group of tools covers analytics — spending by category, monthly income and expenses, budget versus actual, net worth over time, cash flow per month or week. Five of those tools answer in JSON instead of markdown so the figures stay machine-readable: amounts come as whole cents, and each reply includes an `amountsIn` field that spells out the sign conventions. Saved custom reports and dashboards are editable too: create, update and delete reports, add widgets to a page, move and resize them, rename or remove pages. Two prompts ship with it, `financial-insights` and `budget-review`. You need Node.js v16 or higher and a configured Actual Budget instance; Docker Desktop is optional. Local setup is `git clone`, then `npm install` and `npm run build`. Configuration lives in environment variables: `ACTUAL_DATA_DIR` for the data folder, `ACTUAL_SERVER_URL` and `ACTUAL_PASSWORD` for a remote server, `ACTUAL_BUDGET_SYNC_ID` to pick a budget. When the server enforces OpenID login with `ACTUAL_OPENID_ENFORCE=true`, password auth is off, so `ACTUAL_PASSWORD` is useless there — supply `ACTUAL_SESSION_TOKEN` instead, which takes precedence. That token grants full access to your budgets, so treat it like a password. An expired or wrong token does not stop the server from starting; tool calls then fail with an authentication error. ## Requirements - Needs: Node.js (commands run via npx) - Environment variables: `ACTUAL_SERVER_URL`, `ACTUAL_PASSWORD`, `ACTUAL_BUDGET_SYNC_ID`, `ACTUAL_DATA_DIR`, `ACTUAL_BUDGET_ENCRYPTION_PASSWORD`, `ACTUAL_SYNC_TTL_MS` — keys and tokens: ask the human for the values, never commit them or put them in shared files. ## Install ### Claude Code (native platform) **Platform CLI** ```bash claude mcp add --env ACTUAL_SERVER_URL= --env ACTUAL_PASSWORD= --env ACTUAL_BUDGET_SYNC_ID= --env ACTUAL_DATA_DIR= --env ACTUAL_BUDGET_ENCRYPTION_PASSWORD= --transport stdio actual-budget-mcp-server -- npx -y actual-mcp ``` Replace <…> with your own values. 1 more environment variable is in the server README ### Codex **Platform CLI** ```bash codex mcp add actual-budget-mcp-server --env ACTUAL_SERVER_URL= --env ACTUAL_PASSWORD= --env ACTUAL_BUDGET_SYNC_ID= --env ACTUAL_DATA_DIR= --env ACTUAL_BUDGET_ENCRYPTION_PASSWORD= -- npx -y actual-mcp ``` Replace <…> with your own values. 1 more environment variable is in the server README ### Cursor **Config file** File `.cursor/mcp.json`: ```json { "mcpServers": { "actual-budget-mcp-server": { "command": "npx", "args": [ "-y", "actual-mcp" ], "env": { "ACTUAL_SERVER_URL": "", "ACTUAL_PASSWORD": "", "ACTUAL_BUDGET_SYNC_ID": "", "ACTUAL_DATA_DIR": "", "ACTUAL_BUDGET_ENCRYPTION_PASSWORD": "" } } } } ``` Replace <…> with your own values. 1 more environment variable is in the server README ### GitHub Copilot **Config file** File `.vscode/mcp.json`: ```json { "servers": { "actual-budget-mcp-server": { "type": "stdio", "command": "npx", "args": [ "-y", "actual-mcp" ], "env": { "ACTUAL_SERVER_URL": "", "ACTUAL_PASSWORD": "", "ACTUAL_BUDGET_SYNC_ID": "", "ACTUAL_DATA_DIR": "", "ACTUAL_BUDGET_ENCRYPTION_PASSWORD": "" } } } } ``` Replace <…> with your own values. 1 more environment variable is in the server README ### Gemini CLI **Platform CLI** ```bash gemini mcp add -e ACTUAL_SERVER_URL= -e ACTUAL_PASSWORD= -e ACTUAL_BUDGET_SYNC_ID= -e ACTUAL_DATA_DIR= -e ACTUAL_BUDGET_ENCRYPTION_PASSWORD= actual-budget-mcp-server npx -y actual-mcp ``` Replace <…> with your own values. 1 more environment variable is in the server README ## When to use it - check balances across every account at once - filter transactions by date, amount or payee - compare budgeted amounts with what was actually spent - break down spending by category for a month - lay out dashboard widgets and rearrange them ## Example prompts - Show me the balances on all my Actual Budget accounts - Compare budgeted and actual spending by category last month - Add a spending-by-category widget to my dashboard page ## Similar - [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408 - [CCXT](https://affpapa.org/en/nevibecode/mcp/ccxt.md) — MCP server · ★ 44583 - [Finance Toolkit](https://affpapa.org/en/nevibecode/mcp/finance-toolkit.md) — MCP server · ★ 5458 - [EdgarTools](https://affpapa.org/en/nevibecode/mcp/edgartools.md) — MCP server · ★ 2814 - [LetsFG — Flights & Hotels](https://affpapa.org/en/nevibecode/mcp/letsfg-flights-hotels.md) — MCP server · ★ 2188 - [AutoTS](https://affpapa.org/en/nevibecode/mcp/autots.md) — MCP server · ★ 1434 --- NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md