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.
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 and for the
validator record that confirms who paid them),
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:
Or from source, if you would rather build and audit it yourself:
Claude Desktop
claude_desktop_config.json → Settings → Developer → Edit Config:
Restart Claude Desktop. The eleven tools appear under the tools icon.
Claude Code
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
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
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.- Nimiq Pay wallets: Pay moves your NIM through its own contracts (HTLCs) and most of
it comes back. Like the app (its Hide internal switch),
get_summary and
get_statement keep those round trips out of money in/out and report them as
internalIn/internalOut; net counts both. To tell a contract that still holds your
NIM, or that staked it from inside Pay, the server reads each contract you funded that
has not paid it all back (two RPC calls each, at most 40 contracts, kept for 5 minutes).
A busy Pay wallet's first answer can take 15 to 25 seconds. If a contract cannot be
read, payContractsNote says so: NIM still in it may then be counted as sent.
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
NQ82 6GYU …, 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. Only validators pay rewards: the public feed also lists a
stake made in Nimiq Pay (it travels through a contract) as a "restake", so each payer
is checked against Nimiq Watch's validator record and anything that is not a
validator is left out, as in the app since v1.40.0. A payer whose record cannot be
read is kept.- 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
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, the
Nimiq Pay netting (tx by tx against the app's own module, on a real Pay wallet's history), and
the staking legs.
Tests
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.
