README

actual-mcp

An MCP (Model Context Protocol) server that bridges AI/LLM applications to Actual Budget. Exposes your budget data as MCP tools for use with any MCP-compatible client.

Tools

Tool	Description
`list_accounts`	List all accounts (name, type, balance, off-budget/closed flags)
`get_transactions`	Get recent transactions for an account (sorted newest-first)
`add_transaction`	Create a new transaction and commit it to the server
`get_budget_balances`	List budget categories with group and income flag

Setup

Prerequisites

Python 3.12+
An Actual Budget server (self-hosted)
uv (recommended) or pip

Installation

# Clone the repo
git clone https://github.com/slushpupie/actual-mcp
cd actual-mcp

# Install dependencies
uv sync

# Configure your Actual server credentials
cp .env.example .env
# Edit .env with your server URL, password, and budget ID

Configuration

Set these environment variables (or add them to a .env file):

Variable	Required	Description
`ACTUAL_SERVER_URL`	Yes	URL of your Actual Budget server (e.g. `http://localhost:5006`)
`ACTUAL_PASSWORD`	Yes	Your Actual server password
`ACTUAL_BUDGET_ID`	Yes	The budget ID or unique budget name to operate on

Usage

Direct

uv run python mcp_server.py

This starts an MCP server over stdio, ready to connect to an MCP client.

Docker

make build
make run

Or manually:

docker run -i --rm \
  -e ACTUAL_SERVER_URL=http://host.docker.internal:5006 \
  -e ACTUAL_PASSWORD=your_password \
  -e ACTUAL_BUDGET_ID=your_budget_id \
  actual-mcp

Development

# Run tests
uv run python test_mcp_mock.py

# Run with uv
uv run python mcp_server.py

actual-mcp

README

actual-mcp

Tools

Setup

Prerequisites

Installation

Configuration

Usage

Direct

Docker

Development

Recommended Servers