# actual-mcp

An MCP (Model Context Protocol) server that bridges AI/LLM applications to [Actual Budget](https://actualbudget.org/). 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](https://actualbudget.org/) server (self-hosted)
- `uv` (recommended) or `pip`

### Installation

```bash
# 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

```bash
uv run python mcp_server.py
```

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

### Docker

```bash
make build
make run
```

Or manually:

```bash
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

```bash
# Run tests
uv run python test_mcp_mock.py

# Run with uv
uv run python mcp_server.py
```