NimBooks

nimbooks-mcp

一个 MCP 服务，可让 AI 助手读取你的 Nimiq 账簿——余额、分类历史记录、计税成本报表——并起草付款请求和质押链接。

它在你的设备上运行，读取公链数据，无法花费哪怕一枚 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?"

---

它不是什么

请先读这一部分。

• 它从不签名。 此软件包完全不处理密钥——不会生成、存储、读取或推导私钥、助记词或密码短语，也不会索取这些信息。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/ 下的七个文件，约 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 → 设置 → 开发者 → 编辑配置：

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

重启 Claude Desktop。点击工具图标即可看到这十一个工具。

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 中选择：备份 → 复制，然后粘贴到文件中，例如 ~/nimbooks-backup.json，再通过 --backup 传入。若未提供备份文件，list_invoices 会说明这一点，并引导你使用 check_request_paid，该工具会查询区块链。

备份中还包含你的 Cashlink 列表，其中的条目保存着相关链接的私钥，这些链接中可能仍有 NIM。请像保管钱包一样谨慎保管该文件。此服务绝不会打开备份中的这部分内容——并非“读取后丢弃该字段”：它会在入口处直接丢弃，而且有测试确保这些内容绝不会进入输出。

工具

工具	可回答的问题
get_summary	当前余额，以及一段时间内的收入、支出、费用、奖励和交易笔数。
list_transactions	分类后的交易记录——类型、方向、交易对手、备注、哈希。
get_statement	按天列出一年或一个月内的收入和支出，按 CoinGecko 当日 UTC 收盘价计价。
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 位十六进制字符。地址会经过校验和验证：输入错误会被拒绝，绝不会悄悄进行查询。
• 金额会同时以 Luna（整数，精确值）和 NIM（精确十进制字符串）返回。本软件包中不会对金额进行任何浮点运算。
• list_validators 默认返回 50 个池（1 到 50）；除非另有要求，否则也包括未出块的池。验证者列表最多每 10 分钟获取一次。
• get_rewards 仅适用于再质押（复利）池：直接派发型池的奖励会作为普通转入交易到账，并显示在 list_transactions 中。公共奖励数据始于 2025 年 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 和 0.000001，后者比 Luna 的最小单位更小，因此两端都必须拒绝）、备注（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。