Log inSubmit server
Actual Budget MCP Server logo

Actual Budget MCP Server

Connects LLM assistants to Actual Budget for transaction management, account data, budgeting, reports, dashboards, and categories.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Actual Budget MCP Server

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-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "actual-mcp"
      ],
      "env": {
        "ACTUAL_DATA_DIR": "YOUR_VALUE_HERE",
        "ACTUAL_SERVER_URL": "YOUR_VALUE_HERE",
        "ACTUAL_PASSWORD": "YOUR_VALUE_HERE",
        "ACTUAL_BUDGET_SYNC_ID": "YOUR_VALUE_HERE",
        "ACTUAL_SYNC_TTL_MS": "YOUR_VALUE_HERE",
        "ACTUAL_BUDGET_ENCRYPTION_PASSWORD": "YOUR_VALUE_HERE",
        "ACTUAL_SESSION_TOKEN": "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.

We couldn’t confirm it starts correctly

The install command started, but didn't respond the way we expected when we tried to talk to it.

npx -y actual-mcp

initialize succeeded but no response to tools/list.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 19d ago.

Overview

Actual Budget MCP Server MCP server connects LLM assistants to an Actual Budget installation through MCP. It provides read and write operations for accounts, transactions, categories, reports, dashboards, and budgeting data, plus financial analytics such as cash flow and net worth. Use it when an MCP-compatible client needs to inspect or manage personal finance data with natural-language requests. Local data directories, remote Actual servers, password authentication, session tokens, and Docker deployments are supported.

Use cases

  • Inspect account balances and transaction history
  • Create or update Actual Budget transactions
  • Analyze spending, cash flow, and net worth
  • Manage custom reports and dashboard widgets
  • Organize categories and category groups

Key features

  • Transaction and account management
  • Budget and financial reporting
  • Custom report management
  • Dashboard page and widget management
  • Category and category-group management
  • Payee and transaction-rule operations

Tools40

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

Self-reported~162 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.

14/14 checks healthy over the last 30d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

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

Adoption & maintenance

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

GitHub stars285Stargazers on the source repository.
npm downloads3.1kPackage downloads in the last 30 days.
Last commit2d agoMost recent push to the default branch.
Install checkInconclusiveStarted but did not complete the MCP handshake in our test.
Tools exposed40Callable tools this server registers over MCP.
Directory activity4 viewsConfig copies, upvotes, and views on AllMCPs.

How Actual Budget MCP Server works

What Actual Budget MCP Server MCP server does

Actual Budget MCP Server MCP server exposes Actual Budget data and operations to LLM assistants through the Model Context Protocol. It can list accounts, inspect transaction history, create or modify transactions, and return account balance history. The server also provides financial analysis covering category spending, monthly income and expenses, budget-versus-actual comparisons, net worth, category trends, payees, and cash flow.

Write operations extend beyond transactions. The available capabilities include creating, updating, and deleting categories and category groups; managing saved reports; and editing dashboard pages and widgets.

How it works

The server maintains one shared Actual connection during its lifetime and serializes budget operations through that connection. Downloaded data is refreshed after the configured freshness period. Set the synchronization time-to-live to zero to refresh before every call, or to -1 to disable automatic refreshing.

Responses from the reporting tools are JSON. Monetary values are represented as integer cents, and responses include an amountsIn field explaining the sign convention. Reports exclude future-dated transactions from balances and balance histories, while the current month's history is partial. Closed on-budget accounts remain available in historical reports; closed off-budget accounts are excluded by default.

Setup and configuration

Run the project with Node.js 16 or newer and an installed, configured Actual Budget instance. A local installation can be cloned, installed with npm install, and built with npm run build. Docker is optional, and a published image is available as sstefanov/actual-mcp:latest.

For local data, configure ACTUAL_DATA_DIR. For a remote Actual server, use ACTUAL_SERVER_URL with ACTUAL_PASSWORD, or use ACTUAL_SESSION_TOKEN when OpenID authentication disables password login. ACTUAL_BUDGET_SYNC_ID selects a budget, while ACTUAL_SYNC_TTL_MS controls refresh behavior. If encryption uses a separate password, set ACTUAL_BUDGET_ENCRYPTION_PASSWORD.

Claude Desktop is supported through an MCP configuration using either npx or the locally built Node.js entry point. Write access is enabled with the --enable-write argument.

Tools and capabilities

Actual Budget MCP Server MCP server includes tools for:

  • Reading, creating, and updating transactions and accounts.
  • Producing spending, budget, income, cash-flow, net-worth, and trend reports.
  • Creating, updating, and deleting saved custom reports.
  • Reading and organizing dashboard pages and widgets.
  • Managing category groups and categories.
  • Managing payees and transaction rules as documented by the project.

The server also exposes account listings, account details, transaction history, and prompts for financial insights and budget reviews.

Limitations and notes

Actual Budget MCP Server MCP server requires access to an Actual Budget installation or server. Session tokens grant full budget access and should be treated like passwords; expired or invalid tokens allow the process to start but cause tool calls to fail authentication. Operations are serialized through one shared connection, and shutdown waits for in-flight work to finish.

Monthly income uses Actual's income-group metadata. Refunds offset expenses, zero-activity months contribute to averages, and uncategorized transfer pairs are skipped. The former Investments bucket is not included in monthly summaries.

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 MCP Server

Actual Budget MCP Server is an MCP server that connects LLM assistants to Actual Budget. Its main tools read and modify accounts, transactions, categories, reports, dashboards, and payees, while also generating budget, spending, cash-flow, net-worth, and trend analyses from financial data.

Install it by cloning the repository, running `npm install`, and building with `npm run build`, or use the published Docker image. Configure the resulting MCP command in an MCP-compatible client such as Claude Desktop.

The server uses `ACTUAL_DATA_DIR` for local data, `ACTUAL_SERVER_URL` for a remote server, and `ACTUAL_PASSWORD` or `ACTUAL_SESSION_TOKEN` for authentication. Optional settings include `ACTUAL_BUDGET_SYNC_ID`, `ACTUAL_SYNC_TTL_MS`, and `ACTUAL_BUDGET_ENCRYPTION_PASSWORD`.

Yes, Actual Budget MCP Server works with Claude Desktop through its MCP configuration. You can run it with `npx` or a locally built Node.js entry point, and add `--enable-write` when transaction or other write operations are needed.

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 MCP Server AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/actual-budget-mcp-server?style=directory)](https://allmcps.com/mcp/actual-budget-mcp-server)
HTML Embed
<a href="https://allmcps.com/mcp/actual-budget-mcp-server"><img src="https://allmcps.com/api/badge/actual-budget-mcp-server?style=directory" alt="Actual Budget MCP Server on AllMCPs" /></a>