Log inSubmit server
Actual Budget logo

Actual Budget

Connects AI clients to Actual Budget for spending analysis, budget changes, transaction management, and cautious write operations.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Actual Budget

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "actual-budget": {
      "command": "npx",
      "args": [
        "-y",
        "actual-budget-mcp"
      ],
      "env": {
        "ACTUAL_SERVER_URL": "YOUR_VALUE_HERE",
        "ACTUAL_PASSWORD": "YOUR_VALUE_HERE",
        "ACTUAL_BUDGET_ID": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

Actual Budget MCP server connects an Actual Budget instance to MCP-compatible AI clients over a local process. It provides budget, transaction, category, account, schedule, reconciliation, forecasting, and spending-analysis tools, along with operations for creating and changing financial data. Deletes preview the target and require confirmation, while read-only mode can hide write tools. Use it when you want to query or maintain an Actual Budget account through natural-language requests.

Use cases

  • Analyze spending by category and month
  • Forecast end-of-month spending
  • Reconcile an account against a bank balance
  • Create or update transactions with natural-language requests
  • Adjust category budgets and carryover settings

Key features

  • Budget and transaction analysis
  • Natural-language dates in English and Spanish
  • Transaction, transfer, and budget writes
  • Delete previews with confirmation
  • Read-only mode for disabling write tools
  • Multi-currency and sync recovery support

Tools44

What Actual Budget lets your agent do. Expand a tool for its parameters.

Self-reported~576 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 1d ago

Recent health check succeeded.

5/5 checks healthy over the last 45d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 3d ago via OSV.dev · actual-budget-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars17Stargazers on the source repository.
npm downloads2.4kPackage downloads in the last 30 days.
Last commit4d agoMost recent push to the default branch.
Tools exposed44Callable tools this server registers over MCP.
Directory activity3 viewsConfig copies, upvotes, and views on AllMCPs.

How Actual Budget works

What Actual Budget does

Actual Budget MCP server exposes an Actual Budget budget to an MCP client, allowing an AI model to inspect finances and perform selected changes. Read operations cover accounts, balances, budgets, transactions, categories, payees, schedules, rules, and account history. Analysis tools calculate budget-versus-actual results, category trends, spending breakdowns, monthly summaries, and end-of-month projections.

Write operations cover transactions, splits, transfers, budget allocations, category carryover, recategorization, categories, bank synchronization, and reconciliation tasks. The server accepts names such as account or category names instead of requiring users to provide internal IDs, and it can interpret natural-language dates in English and Spanish.

How it works

The server connects to a local or remote Actual Budget server using the Actual Budget server URL, password, and budget Sync ID. MCP clients send tool calls to the local server process, which reads from or updates the selected budget. Output is formatted as tables and summaries rather than raw JSON.

Delete operations show a preview and wait for confirmation before removing data. Setting ACTUAL_READ_ONLY=1 prevents write tools from being exposed to the model. Multi-currency workflows include split handling and reconciliation of accumulated exchange-rate residuals. A recovery path can rebuild local synchronization state when the Actual API and server become out of sync.

Setup and configuration

Actual Budget must already be running locally or remotely. The standard installation paths require Node.js 22.14 or newer. The Claude Desktop extension is an exception: it includes its runtime dependencies and does not require a separate Node.js installation.

For a command-line setup, install or run the npm package with npx and provide these environment variables:

  • ACTUAL_SERVER_URL: URL of the Actual Budget server
  • ACTUAL_PASSWORD: Actual Budget password
  • ACTUAL_BUDGET_ID: budget Sync ID

Claude Code and Claude Desktop can use an npx MCP configuration. Cursor and VS Code provide MCP installation or configuration flows. Claude Desktop also supports a packaged .mcpb extension whose settings UI accepts the server URL, password, and Sync ID; it stores the password and session token in the operating system keychain.

Tools and capabilities

Available operations include:

  • Inspect accounts, balances, budgets, categories, payees, schedules, rules, and transactions.
  • Compare accounts with bank figures and review balance history.
  • Analyze spending by category, category trends, budget-versus-actual results, monthly income and expenses, and projected month-end spending.
  • Create single, bulk, split, and transfer transactions; edit, delete, or recategorize transactions.
  • Set or add budget amounts, move funds between categories, hold unassigned money for the next month, and configure category carryover.
  • Create categories, synchronize linked banks, and reconcile currency residuals.

Limitations and notes

ChatGPT connectors cannot directly start this local stdio server; they require a remote MCP endpoint using HTTPS with SSE or Streamable HTTP. Clients that can run local MCP processes are supported instead, including Claude Desktop, Claude Code, Cursor, VS Code, Gemini CLI, Codex, and local-model setups using Ollama or LM Studio.

Financial data is sent to whichever model the MCP client uses. Running a local model can keep that model interaction on the local machine, depending on the client configuration. Review delete previews and consider read-only mode when granting an agent access to a live budget.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Actual Budget

Actual Budget is an MCP server that connects MCP-compatible AI clients to an Actual Budget instance. Its main tools inspect budgets, accounts, transactions, categories, schedules, and spending analysis, while also supporting transaction creation, budget changes, transfers, reconciliation, and bank synchronization.

Install it with an MCP client using the npm package and `npx`, or install the packaged Claude Desktop `.mcpb` extension. Configure `ACTUAL_SERVER_URL`, `ACTUAL_PASSWORD`, and `ACTUAL_BUDGET_ID` for the command-line route. Standard installations require Node.js 22.14 or newer.

Yes, Actual Budget works with Cursor through its MCP settings. Add the server with `npx -y actual-budget-mcp`, then set the Actual Budget server URL, password, and budget Sync ID in Cursor Settings > MCP.

Yes, it works with local-model setups that can run MCP clients, including Ollama or LM Studio configurations. The server communicates with the client locally, while the budget data goes to whichever model the client uses.

Set `ACTUAL_READ_ONLY=1` to hide write tools from the model. Delete operations also preview what will be removed and wait for confirmation before proceeding.

Related MCP servers

All in Finance & Fintech All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewActual Budget AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/actual-budget?style=directory)](https://allmcps.com/mcp/actual-budget)
HTML Embed
<a href="https://allmcps.com/mcp/actual-budget"><img src="https://allmcps.com/api/badge/actual-budget?style=directory" alt="Actual Budget on AllMCPs" /></a>