NimBooks

nimbooks-mcp

AI アシスタントに Nimiq の帳簿（残高、分類済み履歴、税務基準額の明細書）への読み取りアクセスを提供し、支払いリクエストとステークリンクの下書きを作成できる MCP サーバーです。

お使いのマシン上で動作し、パブリックチェーンを読み取ります。Luna を 1 枚も使用することはできません。

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?"

---

これは何ではないか

まずここをお読みください。

• 署名することはありません。 このパッケージではキーを一切扱いません。秘密鍵、シードフレーズ、パスフレーズを生成、保存、読み取り、導出したり、要求したりすることはありません。create_payment_request と draft_stake が返すのはリンクです。リンクはリクエストまたは入力済みの下書きであり、署名ではありません。資金を動かせるのは支払人のウォレットだけで、その所有者がそこで支払いを承認した場合に限られます。
• 何かを送信することはありません。 トランザクションの構築、ブロードキャスト、キューへの登録は行いません。オンチェーンでも、アプリ内の帳簿でも、支払い済みとして記録することはありません。
• サーバーはありません。 このプロセスが接続するホストは、rpc.nimiqwatch.com（NimBooks アプリがすでに使用している Nimiq の公開 RPC）、v2.nimiqwatch.com（Nimiq Watch の公開分析 API。ステーキング報酬の取得にアプリが使用するものと同じエンドポイント）、validators-api-main.je-cf9.workers.dev（NimBooks アプリが読み取るバリデーターの一覧：名前、手数料、信頼性）、および api.coingecko.com（明細書用の公開日次価格）だけです。nimbooks.subimpact.net を呼び出すことはありません。生成するリンクには、その住所が含まれます。印刷した請求書に住所が記載されているのと同じで、これはデータであり、リクエストではありません。
• 何も書き込みません。 すべてのツールは読み取り専用か、純粋関数です。指定したバックアップファイルは読み取り専用で開きます。
• ウォレットではなく、ウォレットの代わりにもなりません。 指定したアドレスについて、チェーン上ですでに公開されている情報を読み取ります。

不安が残りますか？ サーバー全体は src/ 内の 7 ファイル、約 3,400 行です。ツールのインターフェースは src/index.ts にあり、監査対象はほかにありません。

---

セットアップ

Node 20 以降が必要です。クローンは不要です。npm からインストールします。

npx -y nimbooks-mcp --help

または、ソースから自分でビルドして監査したい場合は、こちらを実行します。

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"
      ]
    }
  }
}

Claude Desktop を再起動します。ツールアイコンの下に 11 個のツールが表示されます。

Claude Code

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

ソースからビルドした場合は、両方のコマンドで npx -y nimbooks-mcp の代わりに node /absolute/path/to/nimbooks/mcp/dist/index.js を指定します。

オプション

フラグ	説明
--address <NQ…>	呼び出し時にアドレスが指定されなかった場合に、アカウントツールが使用するアドレスです。サーバーはこのアドレスをアシスタントに伝えるため、「帳簿の状況はどう？」のような質問でも、毎回アドレスを繰り返さずに済みます。省略可能です。すべてのツールでアドレス引数を指定することもできます。
--backup <path>	NimBooks のバックアップファイルです。必要とするのは list_invoices だけです。

バックアップファイルの取得方法： アプリでは支払いリクエストをサーバーではなく端末に保存するため、ここで表示するにはファイルが必要です。NimBooks で Backup → Copy を選び、~/nimbooks-backup.json などのファイルに貼り付けて、--backup で指定してください。指定しない場合、list_invoices はその旨を伝え、代わりにチェーンに問い合わせる check_request_paid を案内します。

バックアップにはキャッシュリンクの一覧も含まれ、その項目には、まだ NIM を保有している可能性のあるリンクの秘密鍵が含まれています。ウォレットと同じように慎重に保管してください。このサーバーはその部分を開きません。「読み取ってフィールドを破棄する」のではなく、入口で破棄します。また、出力に到達できないことをテストで確認しています。

---

ツール

ツール	回答内容
get_summary	現在の残高に加え、期間内の入出金、手数料、報酬、取引件数を返します。
list_transactions	分類済みの取引行（種類、方向、取引相手、メモ、ハッシュ）を返します。
get_statement	CoinGecko の各日の UTC 終値で評価した、1 年または 1 か月の日ごとの入出金を返します。
create_payment_request	共有可能なリンクを返す支払いリクエストを下書きします。署名は行いません。
draft_stake	アプリのステーキングパネルが入力済みの状態で開く、ステーキングリンクを下書きします。署名は行いません。
check_request_paid	リクエストの参照情報が付いた支払いが届いたかどうかを確認します。
list_invoices	バックアップファイルに保存されたリクエストを返します。
get_staking	ステーキング中のポジション（有効、クールダウン中、終了済み）、プール、手数料、手数料控除後の利回り、アンステーキングまでの時間、初年度の見積もりを返します。
list_validators	アプリの中立的な順序（稼働中のものを先にし、手数料控除後の利回りが高い順に表示し、ピン留めなし）で、バリデータープール、手数料、利回り、中央値を返します。
project_yield	ステーキングした場合に見込まれる年ごとの収益と、その前提条件を明示して返します。
get_rewards	期間内に獲得したプールごとの報酬と、直近 30 日間の実際の利回りを返します。

デフォルトと上限を明確に説明します：

• get_summary と get_statement は最新の取引から最大 1000 件を読み取ります。 check_request_paid は最新の 200 件をスキャンします。上限に達した場合は、その旨を回答に記載します。
• get_summary の期間はデフォルトで取得可能なすべての履歴から現在までです。since／until には YYYY-MM-DD または ISO 8601 を指定でき、UTC として扱われます。
• list_transactions はデフォルトで 50 件、最大 500 件を返します。
• 残高は現在のベーシックアカウント残高であり、期間終了時点の残高ではありません。 ステーキング中の NIM はステーキングコントラクトに保管されているため、別途報告されます。
• ステートメントでは失敗した取引を除外し、送金取引の手数料のみを計上します。また、各 UTC 日の CoinGecko 終値で評価します。その日の終値を取得できない場合、推測値ではなく null を返します。また、部分的な年のデータを合計することはせず、USD の合計額は一切表示しません。
• CoinGecko の公開 API で価格を取得できるのは直近 365 日分のみです。 それより前の年を指定した場合、NIM の数値は引き続き正確ですが、USD 列は空になり、その旨を回答に明記します。NimBooks アプリにも同じ上限があります。有料の CoinGecko キーを使えば上限を解除できますが、このサーバーではキーを受け付けません。キーを受け付けると認証情報を保持することになるためです。
• アドレスは NQ43 Y1RH … の形式、区切りなし、小文字、または 40 桁の 16 進数で入力できます。チェックサムで検証されるため、誤入力は拒否され、気付かれないまま検索されることはありません。
• 金額は Luna（整数、正確）と NIM（正確な小数文字列）の両方で返されます。このパッケージでは、金額の計算に浮動小数点演算を一切使用しません。
• list_validators はデフォルトで 50 個のプール（1～50）を返します。指定しない限り、稼働していないプールも含まれます。バリデーター一覧の取得は 10 分間に最大 1 回です。
• get_rewards が対象とするのは、報酬が再ステーキング（複利運用）されるプールのみです。直接払い出し型プールの報酬は通常の入金取引として届き、list_transactions に表示されます。公開報酬データは 2025 年 1 月から提供されており、最大 1 日遅れることがあります。日ごとの行数は最新の 400 件までです。
• 利回りの数値は予測値として表示されます。供給曲線に伴う発行量の減少をモデル化し、ネットワーク全体のステーキング量は現在の水準に固定しています。いずれも保証ではありません。

---

プロンプトの例

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?

---

アプリとの同等性

ここで作成したリンクは、NimBooks アプリが生成するものとバイト単位で一致していなければ、タップしても開けません。同等性は NimBooks アプリのリポジトリで検証されます。テストスイートはアプリの実際の請求書エンコーダーをインポートし、金額（1、0.5、12.5、100000、および Luna より細かいため両者ともに拒否しなければならない 0.000001）、メモ（ASCII、絵文字／CJK、なし）、有効期限（なし、設定あり）のあらゆる組み合わせについて両者を比較します。さらに、名前付き支払者の有無も含めて比較したうえで、各リンクをアプリ独自のデコーダーに通してラウンドトリップします。トランザクションの分類と明細の集計も同様に、cashlink タグ、nimbooks:invoice:<id> 参照、ステーキングの各項目を含め、行ごとに固定されています。

---

テスト

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 は src/ を対象に実行します。アプリ独自のモジュールとのクロスチェック（請求書とステークリンクのバイト単位の同等性、分類フィクスチャー、明細の集計、stdio ラウンドトリップ）は、リリースごとにアプリのリポジトリで実行されます。

---

ライセンス

MIT。