# nimbooks-mcp [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/subimpact/nimbooks-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1697  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/nimbooks-mcp

## Description
Read-only MCP server for your Nimiq books: balances, history, statements, draft payment requests and stake links. Never signs.

## Tools
Capabilities this server exposes over MCP:

- **get_summary** — Balance and money in/out for a Nimiq address over a window. Read-only: never signs, never sends. Defaults to the full history the public index returns (up to 1000 transactions, newest first). Balance is the live account balance now, not the balance at the end of the window; any staked NIM is reported separately because it lives in the staking contract. Money out includes transfers into the staking contract and out of it — the same treatment as the app’s statement; validator rewards arrive through a separate channel and are reported as their own line (rewardsReceivedNim). Nimiq Pay’s round trips through its own contracts are the wallet’s own money and are reported as internalIn/internalOut, not as money in or out, the same split the app makes; netNim counts both.
- **list_transactions** — Classified transactions for a Nimiq address, newest first. Read-only: never signs, never sends. Each row carries the kind the NimBooks app shows (payment, stake, unstake, reward, swap, vesting), the counterparty, and the memo — a cashlink’s protocol tag reads as "Cashlink" rather than raw bytes, and a `nimbooks:invoice:<id>` memo is the reference that ties a payment to a request.
- **get_statement** — Day-by-day money in and out for a year (or one month of it), priced at the CoinGecko daily close in USD for each UTC day — the same basis the NimBooks tax statement uses. Read-only: never signs, never sends. Failed transactions are excluded and fees are counted on outgoing transactions only. Staking rewards (restaking payouts) are included as in-day income; moving NIM into or out of the staking contract is not a fiat flow, so it is excluded, exactly like the app’s statement. Nimiq Pay’s round trips through its own contracts go in internalInNim/internalOutNim, not in or out, as in the app. Days with no price available come back with closeUsd: null rather than a guess.
- **create_payment_request** — DRAFTS a payment request and returns a shareable link. This never signs anything, never sends anything, and never marks anything paid — the whole request rides inside the link, and only the payer’s wallet, with their approval, can actually move money. The link opens in the NimBooks app; the payment it produces carries the reference nimbooks:invoice:<id>, which check_request_paid looks for later. Note: inside the link, the payload field amountNim is denominated in Luna by the app’s link format; this tool’s own output reports amountNim in NIM and amountLuna in Luna.
- **check_request_paid** — Looks for a payment tagged with a request’s reference (nimbooks:invoice:<id>) in the address’s transactions — the same match the NimBooks app uses to mark a request paid. Read-only: it reports what the chain says and changes nothing, here or in the app. Scans the newest 200 transactions.
- **list_invoices** — Payment requests stored in a NimBooks backup file (the app keeps them on the device; there is no server holding them). Requires the server to be started with --backup <path>. Read-only: the file is never written to, and the cashlink shelf inside it — which holds link private keys — is never opened.
- **get_staking** — A Nimiq address's staking position: active staked, inactive (cooling down after an unstake), retired (ready to withdraw) and total, plus the pool it is staked to with its fee, net yield and payout type, an unstake clock (a retire only becomes valid one full epoch after deactivation), and a first-year rewards estimate at the pool's current net yield. Read-only: reads the public chain and the public validators list, never signs and never sends. Never staked reads as staked: false, never as a failed lookup; a failed lookup is an error that says so.
- **list_validators** — The Nimiq validator pools of the current epoch, ranked neutrally, exactly as the NimBooks app ranks them: producing pools first (those with a reliability score this epoch), best net annual yield first within them, pools that publish no yield last, then the non-producing pools, and the name as the final stable tiebreak. Nothing is pinned first. Read-only: one call to the public validators list, never signs and never sends. netYieldPercent is the net annual yield on the network's total stake after the pool's fee, the Nimiq wallet's convention; it moves as emission falls and as stake moves.
- **project_yield** — Projects what staking an amount of NIM might earn, year by year. With an explicit rate it is a pure offline calculation. Read-only, never signs and never sends. Rate resolution, in order: an explicit annualRatePercent, then the named pool's current net yield, then the median of the producing pools. Compounding follows the pool's payout type (direct pools pay out, the rest restake) unless an explicit compound choice is given. Returns per-year rewards, cumulative rewards and balance, plus its assumptions: emission falls along the protocol supply curve, the network's total stake is held at today's level, and it is a projection, not a promise.
- **get_rewards** — Staking rewards for an address over a window: the total (Luna and NIM), the reward days, the first and last reward date, and the breakdown per paying pool, plus an actual yield over the trailing 30 days measured against the current active stake and the current validator's estimate for comparison. Read-only, never signs and never sends. Important: only restaking (compounding) pools show up in this data; a direct-payout pool's rewards arrive as ordinary incoming transactions and are found with list_transactions instead. The public rewards data starts January 2025, so earlier asks come back empty, and it can lag by a day. A year Nimiq Watch did not answer is named in the answer, never silently dropped.
- **draft_stake** — DRAFTS a stake and returns a link only. This never signs anything and never sends anything: the link opens the NimBooks app with the stake panel pre-filled, and you check the amount and validator there and confirm in your own wallet. No validator is recommended, ranked or chosen for you, and there is no default validator. The link is the deliverable, exactly like create_payment_request: nothing is built, broadcast or queued here, and nothing is marked as staked. Notes explain what the app will do with the values, including a cap to the free balance and the 100 NIM first-stake minimum.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "nimbooks-mcp": {
    "command": "npx",
    "args": ["-y","nimbooks-mcp"]
  }
}
```

## Documentation

## What nimbooks-mcp does

nimbooks-mcp connects an AI assistant to a Nimiq address and exposes read-only financial and staking operations. It can report the live basic-account balance, classify transaction history, produce dated statements, inspect staking positions, compare validator pools, estimate projected yield, and retrieve staking rewards.

The server also supports two drafting operations. `create_payment_request` produces a shareable payment-request link, while `draft_stake` creates a link that opens the app's staking panel with values filled in. Neither operation signs, sends, queues, or marks a payment as complete. The server has no private-key, seed-phrase, or passphrase handling.

## How it works

The process runs on the local machine and reads the public Nimiq chain through `rpc.nimiqwatch.com`. Staking and validator information comes from Nimiq Watch public data and the validator list used by NimBooks. Daily historical prices for statements come from CoinGecko's public API. Generated links contain the NimBooks address needed by the receiving app; creating a link does not contact that application server.

An optional NimBooks backup file supplies locally stored payment requests for `list_invoices`. The file is opened read-only, and cashlink private-key entries are discarded before any data can reach tool output. Without a backup, payment status can still be checked from the chain with `check_request_paid`.

## Setup and configuration

Node.js 20 or newer is required. Install and run the package through npm with `npx -y nimbooks-mcp --help`, or clone the source, install dependencies, build it, and run the resulting `dist/index.js` file.

Use `--address <NQ…>` to set the default account address. This is optional because every tool accepts an address, but it allows questions to refer to the configured account without repeating it. Addresses may be formatted with or without spaces, in lowercase, or as 40 hexadecimal characters; checksum validation rejects malformed values.

Use `--backup <path>` to provide a NimBooks backup file for `list_invoices`. In NimBooks, create the file through Backup → Copy, then pass its path to the process. Treat the file like a wallet because it may contain cashlink private keys, even though this server does not expose those entries.

The README includes configurations for Claude Desktop and Claude Code using the npm command or an absolute path to the built JavaScript file.

## Tools and capabilities

- `get_summary` reports the current balance, money in and out, fees, rewards, transaction counts, and Nimiq Pay internal transfers over a date window.
- `list_transactions` returns classified rows with direction, kind, counterparty, memo, and transaction hash.
- `get_statement` provides daily activity and CoinGecko UTC closing prices for a month or year.
- `create_payment_request` drafts a shareable payment request without signing it.
- `draft_stake` drafts a pre-filled staking link without moving funds.
- `check_request_paid` checks whether a request reference appears on chain.
- `list_invoices` reads stored payment requests from the supplied backup.
- `get_staking`, `list_validators`, `project_yield`, and `get_rewards` cover positions, pools, projected returns, and observed rewards.

Amounts are returned in exact Luna integers and decimal NIM strings. Staking balances are reported separately from the live basic-account balance. Nimiq Pay contract round trips are separated into internal inflow and outflow fields where the relevant contract data can be read.

## Limitations and notes

Summary and statement operations inspect up to 1,000 newest transactions, while payment-status checks inspect up to 200. Transaction listings return 50 rows by default and allow up to 500. Pay-contract analysis can make an initial response take 15–25 seconds for a busy account.

CoinGecko's public price history covers only the last 365 days. Older statements retain exact NIM amounts but omit USD values. Missing daily prices are returned as null, and USD totals are withheld when the period has incomplete pricing. Reward data covers restaking pools, begins in January 2025, may lag by one day, and is capped at the newest 400 daily rows. Yield results are projections based on stated assumptions, not guarantees.

The server does not send transactions, manage a wallet, write to books, or replace a wallet application. Direct-payout staking rewards appear as ordinary incoming transactions rather than in the restaking rewards feed.

_Full upstream README: https://allmcps.com/mcp/nimbooks-mcp/readme_