# Actual Budget MCP Server

An MCP server for [Actual Budget](https://actualbudget.org) built with [FastMCP](https://gofastmcp.com) and [actualpy](https://github.com/bvanelli/actualpy).

## Requirements

- Python 3.11+
- [uv](https://docs.astral.sh/uv/getting-started/installation/)
- A running Actual Budget server

## Setup

```bash
git clone https://github.com/Saikumarmohan/actual-budget-mcp
cd actual-budget-mcp
uv sync
```

## Configuration

All configuration is done via environment variables. Pass them via your MCP client config.

| Variable | Required | Default | Description |
|---|---|---|---|
| `ACTUAL_BASE_URL` | ✅ | - | URL of your Actual Budget server |
| `ACTUAL_PASSWORD` | ✅ | - | Actual Budget server password |
| `ACTUAL_FILE` | ✅ | - | Budget file name or sync id |
| `ACTUAL_CURRENCY` | ❌ | `USD` | Currency code e.g. `INR`, `EUR` |
| `ACTUAL_CURRENCY_SYMBOL` | ❌ | `$` | Currency symbol e.g. `₹`, `€` |
| `ACTUAL_TIMEZONE` | ❌ | `UTC` | Timezone e.g. `Asia/Kolkata`, `America/New_York` |
| `ACTUAL_MCP_TRANSPORT` | ❌ | `stdio` | Transport mode — `stdio` for Cline/Cursor, `http` for Docker |
| `ACTUAL_MCP_HOST` | ❌ | `0.0.0.0` | Host to bind to in HTTP mode |
| `ACTUAL_MCP_PORT` | ❌ | `8000` | Port to bind to in HTTP mode |

## MCP Client Config (Cline / Cursor)

Replace `/path/to/actualbudgetpy` with the absolute path to this project on your machine.

```json
{
  "mcpServers": {
    "actualbudget": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/actualbudgetpy",
        "-m",
        "actualbudgetpy.server"
      ],
      "env": {
        "ACTUAL_BASE_URL": "http://localhost:5006",
        "ACTUAL_PASSWORD": "your_password",
        "ACTUAL_FILE": "your_file_id_or_name",
        "ACTUAL_CURRENCY": "USD",
        "ACTUAL_CURRENCY_SYMBOL": "$",
        "ACTUAL_TIMEZONE": "UTC"
      }
    }
  }
}
```

> **Note:** On Windows, use the full path to `uv.exe` instead of just `uv` e.g. `C:\\Users\\username\\.local\\bin\\uv.exe`

## HTTP Mode (Local)

For running as a standalone HTTP server locally:

1. Copy `.env.example` to `.env` and fill in your values:
```bash
cp .env.example .env
```

2. Set transport to `http` in your `.env`:
```
ACTUAL_MCP_TRANSPORT=http
```

3. Start the server:
```bash
uv run -m actualbudgetpy.server
```

4. Point your MCP client to `http://localhost:8000/mcp`:
```json
{
  "mcpServers": {
    "actualbudget": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

## Docker

```bash
# build
docker build -t actualbudgetpy .

# run
docker run -p 8000:8000 \
  -e ACTUAL_BASE_URL=http://your-server:5006 \
  -e ACTUAL_PASSWORD=your_password \
  -e ACTUAL_FILE=your_file_id \
  -e ACTUAL_CURRENCY=USD \
  -e ACTUAL_CURRENCY_SYMBOL=$ \
  -e ACTUAL_TIMEZONE=UTC \
  actualbudgetpy
```

Then point your MCP client to `http://localhost:8000/mcp`.

## Available Tools

### Read
| Tool | Description |
|---|---|
| `list_accounts` | List all accounts |
| `list_payees` | List all payees |
| `list_transactions` | List transactions with optional filters — date, account, category, payee, notes |
| `list_categories` | List all categories, filterable by income or expense |
| `list_category_groups` | List all category groups |
| `list_budgets` | List budget allocations by month |

### Write
| Tool | Description |
|---|---|
| `add_transaction` | Create a new transaction |
| `update_transaction` | Update an existing transaction |
| `delete_transaction` | Delete a transaction by id |
| `create_transfer` | Transfer money between two accounts |
| `set_budget` | Set budget amount for a category in a month |

## Resources

Resources are read-only data the AI can attach as context at the start of a conversation.

| Resource | Description |
|---|---|
| `budget://accounts` | Live list of all accounts |
| `budget://categories` | Live list of all categories |

## Prompts

Reusable prompt templates that guide the AI through common workflows.

| Prompt | Parameters | Description |
|---|---|---|
| `monthly_review` | `month` (YYYY-MM) | Full budget vs spending analysis for a month |
| `spending_by_category` | `category`, `start_date`, `end_date` | Spending breakdown for a specific category |
| `add_expense` | `description` | Natural language guided expense entry |

## Author

Built by [Saikumar](https://www.linkedin.com/in/saikumar-mohan/) — feel free to connect!

If you find this useful, consider giving it a ⭐ on GitHub.