# akahu-mcp

An [MCP](https://modelcontextprotocol.io) server that exposes [Akahu](https://akahu.nz) (New Zealand open-banking) data to LLM agents like Claude. Lets the agent list your bank accounts, inspect your investment holdings, and pull transactions for analysis.

A local SQLite cache (`cache.db`) keeps the last ~90 days of transactions on disk and refreshes incrementally. The cache TTL is 24h to match Akahu Personal's once-a-day upstream refresh; agents can pass `force=True` on any tool to bypass it.

## Tools

- `list_accounts(force=False)` — bank/depository accounts with balances. Sharesight is excluded.
- `get_share_holdings(force=False)` — Sharesight portfolio: total value, breakdown (returns / capital / currency / dividends), and per-holding rows.
- `list_transactions(account, start=None, end=None, limit=100, force=False)` — transactions for one account from the local cache, refreshing from Akahu first if the cache is older than 24h. `account` matches by id or fuzzy name substring.

## Setup

1. Install [`uv`](https://docs.astral.sh/uv/) if you don't have it.
2. Set up an [Akahu **Personal App**](https://developers.akahu.nz/docs/personal-apps) — these are free, single-user apps you create against your own Akahu account. You'll get an `app_token` (the personal app's id) and a `user_token` for yourself.
3. Create a `.env` file in the project root:
   ```
   AKAHU_USER_TOKEN=user_token_xxx
   AKAHU_APP_TOKEN=app_token_xxx
   ```
4. `uv sync` to install dependencies.
5. Smoke-test: `uv run python -m akahu_mcp.sync` — should print your accounts and fetch transactions for the first one.

## Wiring it into an MCP host

### Claude Code

```bash
claude mcp add akahu --scope user -- uv --directory /absolute/path/to/akahu-mcp run akahu-mcp
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent on your platform:

```json
{
  "mcpServers": {
    "akahu": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/akahu-mcp", "run", "akahu-mcp"]
    }
  }
}
```

If your host can't find `uv` on PATH, replace `"uv"` with the absolute path from `which uv`.

## Notes

- Built and tested against [Akahu Personal Apps](https://developers.akahu.nz/docs/personal-apps), which only refresh upstream data once per day — hence the 24h cache TTL. The same endpoints exist on commercial plans, but TTLs may be worth shortening there.
- `legacy/` contains the two original scripts (`akahu.py`, `list_accounts.py`) that this project grew out of. They still work standalone — install their deps with `uv sync --group legacy`, then `uv run --group legacy python legacy/list_accounts.py`.