goblin-mny

Ask Claude about your money. A local MCP server over your New Zealand bank accounts, synced from Akahu.

Everything runs on your machine. Your transactions live in a SQLite file in your home directory, your Akahu tokens never leave it, and there is no hosted component — nothing to sign up for beyond Akahu itself.

The successor to bobtronic/mny, which did this with fish, curl and jq.

What you can ask

"What did I spend on groceries last month, and how does that compare to my average?"

"Find every subscription I'm paying for and what they cost me a year."

"I think I'm still being charged for a gym I cancelled — check?"

"How much did eating out cost me in 2025 vs 2026 so far?"

"Show me every transaction over $500 in the last six months."

"Am I spending more than I earn? Break it down by month."

Answers come out of the local cache, so they're instant, work offline, and can span your entire history without paging an API.

Related MCP server: akahu-mcp

How it works

   ┌──────────┐   sync    ┌──────────────────┐   MCP tools   ┌────────┐
   │  Akahu   │ ────────▶ │  local SQLite    │ ────────────▶ │ Claude │
   │   API    │           │  + FTS5 search   │               │        │
   └──────────┘           └──────────────────┘               └────────┘
        │                    ~/.goblin-mny/
        ▼
   your bank

Akahu is the only thing that talks to your bank. goblin-mny pulls from Akahu into a local cache and answers questions from there.

Setup

Full instructions: SETUP.md — written so a coding agent can do the install for you. The short version:

# Download a prebuilt binary (or build from source with `bun run build`)
curl -fsSL -o goblin-mny https://github.com/super-turbo-engineer/goblin-mny/releases/latest/download/goblin-mny-linux-x64
install -m 755 goblin-mny ~/.local/bin/

goblin-mny init                       # then paste your Akahu tokens into the config
goblin-mny doctor                     # verify credentials
goblin-mny sync                       # pull your history
goblin-mny diagnose --write           # learn your bank's transfer patterns
claude mcp add goblin-mny -s user -- ~/.local/bin/goblin-mny serve
goblin-mny install-skill              # the skill is embedded in the binary

You need a New Zealand bank account. Akahu supports ANZ, ASB, BNZ, Kiwibank, Westpac, TSB, The Co-operative Bank, Heartland and Rabobank. Sign up at https://my.akahu.nz (identity verification and 2FA required), connect the accounts you want counted, then create a free personal app at https://my.akahu.nz/developers for the two tokens.

Connecting the accounts is the step people miss — the personal app grants API access, it doesn't connect anything by itself. Connect all of them, not just your everyday account: transfers between your own accounts can only be recognised when both ends are present.

The tokens grant full read access to your bank data — put them in ~/.goblin-mny/config.json yourself, never into a chat window.

Not OAuth. Akahu's OAuth flow is for full commercial apps, which need a commercial agreement and would route your bank data through somebody else's app. Personal apps keep each person's data entirely their own — which is why everyone runs their own copy of this.

Prebuilt binaries for Linux, macOS and Windows (x64 + arm64) are on the releases page. macOS builds are unsigned — clear the quarantine flag with xattr -d com.apple.quarantine ~/.local/bin/goblin-mny.

Try it without a bank account

goblin-mny seed-demo    # 18 months of synthetic data

Tools

list_accounts reports balances grouped by type rather than as one total — spendable (checking + savings), restricted (KiwiSaver, locked until retirement) and owed (cards and loans, negative). Summing those into a single "net worth" produces a number that reads as available money while including funds you can't touch for decades.

Why the tools don't mirror the Akahu API

The obvious design is to proxy Akahu's REST shape and cache the responses. It's the wrong shape for a model.

Ask "how much did I spend on coffee last month" through a cursor-paginated /transactions endpoint and the model pages tens of thousands of tokens of JSON into its context, then does the arithmetic itself — slowly, and sometimes wrongly.

The entire reason for a local database is that aggregation can happen before the answer reaches the context window. So the tools are task-shaped, not endpoint-shaped: they return totals, trends and small capped result sets. query_sql covers the long tail — call it with no arguments and it returns the schema.

Storage, on the other hand, is a faithful mirror: same _ids, same field names, and the untouched API response in raw_json, so new columns can be backfilled without re-syncing.

Design notes

Sign convention is Akahu's throughout: amount is negative for money out, positive for money in.

Incremental sync re-fetches a rolling window (lookbackDays, default 30) rather than resuming from the newest row it holds. Akahu revises transactions in place after they settle, and merchant enrichment can arrive days late — so "everything newer than my newest row" would permanently miss those revisions. Upserting by _id makes the overlap free.

Pending transactions get their own table, replaced wholesale each sync. They mutate and then vanish when they settle, reappearing in transactions under a different _id; keeping them separate means they can never double-count.

Full-text search, not embeddings. Bank descriptions are short, abbreviated and mostly structured, and Akahu already supplies merchant and category enrichment — which is precisely the labelling a vector store would be straining to recover from COUNTDOWN 1234 AUCKLAND. FTS5 over description, merchant and the particulars/code/reference fields covers it at zero cost. A vector index can be added later as an additive migration if fuzzy grouping proves genuinely necessary.

Internal transfers and credit-card repayments are not spending, and are excluded from spending_summary, cashflow and recurring_charges by default. Moving $500 into savings isn't $500 spent, and paying off a card double-counts the purchases it settles — those were already counted on the card account. On the demo fixtures, counting them overstated spending by 48%. Cashflow was worse: income and expenses inflate by the same amount, so net stays correct while both components are wrong, which is exactly the kind of bug a spot-check misses. The excluded amount is always reported in excludedInternalTransfers; pass include_transfers to reconcile against a raw statement.

Credit-card repayments are excluded only where the card's own history covers the date. The exclusion exists to stop double-counting purchases already recorded on the card — but banks commonly expose only a few months of card history, and plenty of people repay a card they never connected. In both cases the repayment is the only record of that spending, and dropping it understates real outgoings. So the guard is date-bounded, not a simple "is a card connected" check.

Bank-specific patterns live in the user's rules file, never in the codebase. The detectors here work off Akahu's own type vocabulary and off structure — paired legs across connected accounts. Nothing keys off description formats, which differ per institution. goblin-mny diagnose bridges the gap per user.

Recurring detection needs two signals, not one: a regular cadence and a stable amount. Regular-but-variable is a habit (weekly groceries), not a subscription. Payees Akahu didn't enrich are grouped by a normalised description, which strips the receipt numbers and store codes that would otherwise split one payee into forty.

Cashflow averages exclude the current period, because a part-month otherwise reads as a spending drop.

query_sql is guarded twice: it runs on a separately-opened read-only connection, and rejects anything that isn't a single SELECT/WITH.

All SQL goes through src/sqlite.ts, a thin adapter over bun:sqlite. It exists because bun:sqlite binds named parameters only when the object keys carry the placeholder sigil: given @id in the statement, a key of id doesn't throw — it silently binds NULL and reports success. With a NULL primary key an ON CONFLICT clause never fires either, so upserts quietly accumulate duplicate empty rows. The adapter normalises keys and throws on any placeholder the caller didn't supply, turning an invisible corruption into a loud error. bun test covers it.

Development

bun install
bun test                     # adapter + environment assumptions
bun run typecheck
bun run dev -- doctor        # run the CLI from source
bun run serve                # run the MCP server from source
bun run build                # single executable -> dist/goblin-mny
bun run build:all            # cross-compile every platform

Runtime is Bun (bun:sqlite is built in, which is what makes the single-file executable possible — a native module like better-sqlite3 can't be embedded this way). Nothing is required at run time: the binary is self-contained.

CLI

goblin-mny init            Create the config file
goblin-mny doctor          Verify config, credentials and database
goblin-mny sync [--full]   Pull from Akahu into the cache
goblin-mny status          Cache freshness and coverage
goblin-mny accounts        Accounts and balances
goblin-mny top [N]         Top N spending categories, last 90 days
goblin-mny serve           Run the MCP server on stdio
goblin-mny seed-demo       Synthetic data for trying it out

Limitations

• New Zealand only — Akahu covers NZ institutions.

• Read-only. Personal apps can't initiate payments, and this server exposes no write path to your accounts by design.

• No webhooks on personal apps, so freshness is sync-driven.

• Akahu personal apps refresh from the bank once daily (manual refresh has a 1-hour cooldown). Syncing more often returns the same data — the cache isn't stale because sync is broken.

• One user per install. A personal app is scoped to its owner's Akahu account. Each person runs their own copy with their own tokens — which is the point.

Licence

MIT