akahu-mcp

MCP server exposing the Akahu banking API as tools - list accounts, get a balance, get settled and pending transactions, check connection health.

Every tool is read-only. This server backs an Akahu personal app, which by definition cannot make payments or subscribe to webhooks - the only side effect it can produce is asking Akahu to refresh from the bank, behind an explicit refresh flag.

Features

MCP Tools

• list_accounts list every account Akahu has access to, with balance, credit limit, status and last-refreshed timestamps.
• bank_get_balance, bank_get_transactions look up a specific account by its Akahu account ID.
• bank_get_all_transactions - settled transactions across every account at once, for finding a payment without knowing which account it went through.
• bank_get_pending_transactions - money committed but not yet posted, which no balance reflects yet.
• bank_get_connection_health - whether each bank connection is still active, and how stale its data is.

Installation

git clone git@github.com:adrianparker/akahu-mcp.git
cd akahu-mcp
npm install
cp .env.example .env

Fill in .env:

NODE_ENV=app
AKAHU_APP_TOKEN=app_token_...
AKAHU_USER_TOKEN=user_token_...

Get your Akahu tokens from developers.akahu.nz. Use npm run cli -- list-accounts to find the account IDs to pass to balance/transactions.

Usage

As an MCP server

npm start

Runs src/index.js on stdio and waits for JSON-RPC input - that's normal, Ctrl+C to stop. For an interactive check of the tool calls before wiring it into Claude, use the official inspector:

npx @modelcontextprotocol/inspector npm start

Wire it into Claude by adding an entry to your MCP client config (e.g. claude_desktop_config.json, or a project .mcp.json):

{
  "mcpServers": {
    "akahu-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/akahu-mcp/src/index.js"]
    }
  }
}

src/index.js loads .env itself (resolved relative to its own file, not the launching process's cwd), so you don't need to pass tokens through the MCP client config.

Tools

• list_accounts - { refresh?: boolean }. Every account Akahu has access to, including balance (current, available, limit, overdrawn, currency), status, attributes and when Akahu last refreshed each one.
• bank_get_balance - { account: string, refresh?: boolean }. account is the Akahu account ID (see list_accounts). refresh: true asks Akahu to refresh from the bank first, then polls until the refresh lands (up to 30s) before reading the balance.
• bank_get_transactions - { account: string, start?: string, end?: string }. account is the Akahu account ID. Dates are ISO 8601; start is exclusive, end is inclusive (Akahu's own semantics). Omit both for everything the app can access. Paginates internally, so you always get the full result in one call.
• bank_get_all_transactions - { start?: string, end?: string }. The same settled transactions, across every account in one sweep. Each row carries its account ID, and the response includes an accounts lookup mapping those IDs to a bank and account name.
• bank_get_pending_transactions - { account?: string }. Pending (unsettled) transactions; omit account for every account. Pending rows are not stable - date, description and amount can all change before they settle, and they carry no ID. Payments made through Akahu itself never appear here.
• bank_get_connection_health - no arguments. Per bank connection: whether every account on it is still ACTIVE, and how many hours since Akahu last pulled fresh balance and transaction data. Most stale first.

Transactions are returned enriched where Akahu has the data: merchant, category (NZFCC name plus its higher-level group), and meta with the particulars, code, reference, otherAccount and cardSuffix a NZ bank carries on a direct debit or credit.

Both transaction tools paginate internally and return a truncated flag. If it is true the date range was too wide to return in full (20 pages per account, 50 across all accounts) and transactions are missing — narrow the range and call again.

From the command line

For a human, not an MCP client - same data, rendered as a table:

npm run cli -- list-accounts
npm run cli -- balance acc_...
npm run cli -- balance acc_... --refresh
npm run cli -- transactions acc_... --start 2026-01-01 --end 2026-02-01
npm run cli -- all-transactions --start 2026-01-01 --end 2026-02-01
npm run cli -- pending
npm run cli -- pending acc_...
npm run cli -- connection-health

Or use the akahu bin directly once installed globally / linked, so you don't need the npm run cli -- prefix:

akahu balance acc_...

To install globally from this checkout (picks up package.json's bin entry):

npm install -g .

For development, npm link instead - it symlinks the global akahu bin back to this checkout, so edits to src/cli.js take effect immediately without reinstalling:

npm link

Either way, .env is resolved relative to the current working directory (via dotenv.config() in src/cli.js), not the checkout - so run akahu from a directory containing a filled-in .env, or export AKAHU_APP_TOKEN/AKAHU_USER_TOKEN in your shell. To remove a global install or link later: npm uninstall -g akahu-mcp (works for both).

Development

Run Tests

npm test
npm run test:watch

Coverage

npm run coverage

100% coverage is the bar for this project - src/index.js and src/cli.js carry a c8 ignore around their if (import.meta.url === ...) entrypoint guard, since that only runs when the bin is actually executed, not under unit tests.

Lint

npm run lint

License

AGPL-3.0-only — see LICENSE.