nimbooks-mcp

An MCP server that gives an AI assistant read access to your Nimiq books — balances, classified history, tax-basis statements — and lets it draft payment requests and stake links.

It runs on your machine, reads the public chain, and cannot spend a single Luna.

you:      "How much came in last month, and who from?"
you:      "Draft a request for 25 NIM for the September retainer."
you:      "Has anyone paid request a1b2c3d4e5 yet?"

What it is not

This is the part to read first.

• It never signs anything. There is no key handling in this package at all — nothing generates, stores, reads, derives or asks for a private key, a seed phrase or a passphrase. create_payment_request and draft_stake return links. A link is a request or a pre-filled draft, never a signature. Only the payer's wallet can move money, and only when its owner approves the payment there.
• It never sends anything. No transaction is built, broadcast or queued. Nothing is marked paid — not on chain, and not in your app's own books.
• It has no server. The only hosts this process contacts are rpc.nimiqwatch.com (the public Nimiq RPC the NimBooks app already uses), v2.nimiqwatch.com (Nimiq Watch's public analytics API, the same endpoint the app reads for staking rewards), validators-api-main.je-cf9.workers.dev (the validator list the NimBooks app reads: names, fees, reliability) and api.coingecko.com (public daily prices, for statements). It never calls nimbooks.subimpact.net. The links it mints contain that address, the way a printed invoice carries a street address: that is data, not a request.
• It writes nothing. Every tool is a read or a pure function. The backup file you point it at is opened read-only.
• It is not a wallet, and not a replacement for one. It reads what the chain already says in public about an address you name.

Not sure? The whole server is seven files under src/, about 3,400 lines. src/index.ts is the tool surface; there is nothing else to audit.

Setup

Node 20 or newer. Nothing to clone — from npm:

npx -y nimbooks-mcp --help

Or from source, if you would rather build and audit it yourself:

git clone https://github.com/subimpact/nimbooks-mcp
cd nimbooks-mcp
npm install
npm run build     # → dist/index.js

Claude Desktop

claude_desktop_config.json → Settings → Developer → Edit Config:

{
  "mcpServers": {
    "nimbooks": {
      "command": "npx",
      "args": [
        "-y", "nimbooks-mcp",
        "--address", "NQ43 Y1RH P1K7 JH78 LRTS 95RY GAUU UBDK FFGX"
      ]
    }
  }
}

Restart Claude Desktop. The eleven tools appear under the tools icon.

Claude Code

claude mcp add nimbooks -- npx -y nimbooks-mcp \
  --address "NQ43 Y1RH P1K7 JH78 LRTS 95RY GAUU UBDK FFGX"

Built from source instead? Point both commands at node /absolute/path/to/nimbooks/mcp/dist/index.js in place of npx -y nimbooks-mcp.

Options

| Flag | What it does | | --- | --- | | --address <NQ…> | The account tools use when a call doesn't name one; the server tells the assistant about it, so questions like "how are my books looking?" work without repeating your address. Optional — every tool also takes an address argument. | | --backup <path> | A NimBooks backup file. Only list_invoices needs it. |

Getting a backup file: the app keeps your payment requests on the device, not on a server — so a file is the only way to show them here. In NimBooks: Backup → Copy, then paste into a file, e.g. ~/nimbooks-backup.json, and pass it with --backup. Without it, list_invoices says so and points at check_request_paid, which asks the chain instead.

A backup also contains your cashlink shelf, and those entries hold the private keys of links that may still hold NIM. Keep the file as carefully as a wallet. This server never opens that part of it — not "reads it and drops the field": it is discarded at the door, and a test asserts it can never reach the output.

The tools

| Tool | Answers | | --- | --- | | get_summary | Balance now, plus money in/out, fees, rewards and transaction counts over a window. | | list_transactions | Classified rows — kind, direction, counterparty, memo, hash. | | get_statement | Day-by-day in/out for a year or month, priced at each day's CoinGecko UTC close. | | create_payment_request | Drafts a request and returns a shareable link. Signs nothing. | | draft_stake | Drafts a stake link that opens the app's stake panel pre-filled. Signs nothing. | | check_request_paid | Whether a payment tagged with a request's reference has landed. | | list_invoices | Requests stored in your backup file. | | get_staking | The staked position: active, cooling down, retired, the pool, fee, net yield, an unstake clock, and a first-year estimate. | | list_validators | The validator pools in the app's neutral order (producing first, best net yield first, nothing pinned), with fees, yields and the median. | | project_yield | What staking an amount might earn, year by year, with its assumptions spelled out. | | get_rewards | The rewards earned in a window, per pool, with an actual yield over the trailing 30 days. |

Defaults and limits, stated plainly:

• get_summary and get_statement read up to the newest 1000 transactions; check_request_paid scans the newest 200. When a cap is hit, the answer says so.
• get_summary windows default to all available history → now. since/until take YYYY-MM-DD or ISO 8601, read as UTC.
• list_transactions returns 50 rows by default, 500 at most.
• Balance is the live basic-account balance, not the balance at the end of a window. Staked NIM lives in the staking contract, so it is reported separately.
• Statements exclude failed transactions, count fees on outgoing transactions only, and price each UTC day at that day's CoinGecko close. A day with no close available comes back null rather than a guess — and the USD totals are withheld entirely rather than summed from a partial year.
• CoinGecko's public API only serves the last 365 days of prices. Ask for an older year and the NIM figures are still exact, but the USD columns come back empty — and the answer says so, in those words. The NimBooks app has the same ceiling. A paid CoinGecko key would lift it; this server does not take one, because taking one would mean holding a credential.
• Addresses may be typed NQ43 Y1RH …, flat, lower-case, or as 40 hex characters. They are checksum-validated: a typo is refused, never quietly looked up.
• Amounts come back in both Luna (integer, exact) and NIM (exact decimal string). No float arithmetic touches money anywhere in this package.
• list_validators returns 50 pools by default (1 to 50); non-producing pools are included unless you ask otherwise. The validator list is fetched at most once per 10 minutes.
• get_rewards only sees restaking (compounding) pools: a direct-payout pool's rewards arrive as ordinary incoming transactions and show up in list_transactions. The public rewards data starts January 2025 and can lag by a day; per-day rows are capped at the newest 400.
• Yield figures are labelled as projections: emission falling with the supply curve is modelled, the network's total stake is held at today's level, and none of it is a promise.

Example prompts

What's the balance, and how much came in during August?
Show me the last 20 transactions — anything that wasn't a plain payment?
Statement for September 2026, with the USD close for each day.
Draft a payment request for 12.5 NIM, memo "September retainer", expiring in 7 days.
Has request a1b2c3d4e5 been paid?
List my saved payment requests and tell me which are still open.
What is my stake earning?
Which pools pay the most right now?
If I stake 1,000 NIM for 3 years, what might I earn?
What rewards did I earn this year, and from which pool?

Parity with the app

A link drafted here must be the same bytes the NimBooks app would have produced, or it won't open when someone taps it. Parity is enforced in the NimBooks app repository: its test suite imports the app's real invoice encoder and compares the two across every combination of amount (1, 0.5, 12.5, 100000, and 0.000001, which both sides must refuse, being finer than a Luna), memo (ASCII, emoji/CJK, none) and expiry (none, set), with and without a named payer, then round-trips each link back through the app's own decoder. Transaction classification and statement aggregation are pinned the same way, row for row, including the cashlink tag, the nimbooks:invoice:<id> reference, and the staking legs.

Tests

npm test       # offline: backup parsing, including malformed entries and the cashlink-secret fence
npm run smoke  # opt-in: drives the built server against a live demo wallet over stdio

npm run typecheck covers src/. The cross-checks against the app's own modules (invoice and stake-link byte-parity, classification fixtures, statement aggregation, stdio round trip) run in the app repository on every release.

Licence

MIT.