akahu-mcp

An MCP server that exposes Akahu (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 if you don't have it.

2. Set up an Akahu Personal App — 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

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:

{
  "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, 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.