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.

Related MCP server: LunchMoney MCP Server

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.