# Actual Budget MCP Server [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/s-stefanov/actual-mcp  
**GitHub Stars:** 285  
**npm Downloads (last month):** 3143  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/actual-budget-mcp-server

## Description
MCP server exposing Actual Budget accounts, transactions, budgets and reporting to LLM assistants.

## Tools
Capabilities this server exposes over MCP:

- **get-transactions**
- **create-transaction**
- **update-transaction**
- **get-accounts**
- **balance-history**
- **spending-by-category**
- **monthly-summary**
- **budget-vs-actual**
- **net-worth**
- **category-trends**
- **spending-by-payee**
- **cash-flow**
- **get-custom-reports**
- **create-custom-report**
- **update-custom-report**
- **delete-custom-report**
- **get-dashboards**
- **add-dashboard-widget**
- **update-dashboard-widget**
- **remove-dashboard-widget**
- **organize-dashboard**
- **create-dashboard-page**
- **rename-dashboard-page**
- **delete-dashboard-page**
- **get-grouped-categories**
- **create-category**
- **update-category**
- **delete-category**
- **create-category-group**
- **update-category-group**
- **delete-category-group**
- **get-payees**
- **create-payee**
- **update-payee**
- **delete-payee**
- **merge-payees**
- **get-rules**
- **create-rule**
- **update-rule**
- **delete-rule**

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "actual-budget-mcp-server": {
    "command": "npx",
    "args": ["-y","actual-mcp"],
    "env": {
      "ACTUAL_DATA_DIR": "",
      "ACTUAL_SERVER_URL": "",
      "ACTUAL_PASSWORD": "",
      "ACTUAL_BUDGET_SYNC_ID": "",
      "ACTUAL_SYNC_TTL_MS": "",
      "ACTUAL_BUDGET_ENCRYPTION_PASSWORD": "",
      "ACTUAL_SESSION_TOKEN": ""
    }
  }
}
```

**Requires environment variables:** `ACTUAL_DATA_DIR`, `ACTUAL_SERVER_URL`, `ACTUAL_PASSWORD`, `ACTUAL_BUDGET_SYNC_ID`, `ACTUAL_SYNC_TTL_MS`, `ACTUAL_BUDGET_ENCRYPTION_PASSWORD`, `ACTUAL_SESSION_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/actual-budget-mcp-server/readme_