nwc-mcp

nwc-mcp

为你的 LLM Agent 提供的 Lightning 钱包。 MCP 服务将 Nostr Wallet Connect（NIP-47）钱包操作封装为 Agent 可调用的工具——读取余额、生成发票、支付发票、支付 Lightning 地址、支付 LNURL、批量支付、keysend——并通过纵深防御安全机制加以保护。

将其接入 Claude Desktop、Claude Code、Cursor 或任何支持 MCP 的客户端。为 Agent 提供一个子钱包（而非你的主钱包），设置每日限额，然后让它在你设定的范围内代你支出 sats。

v0.2 — 所有支出工具均已推出。 共 12 个工具（7 个读取/收款 + 5 个支出 + 1 个确认）、4 道安全关卡和完整的审计日志。已通过 ZEUS 路由，在 Alby Hub + Olympus 上完成端到端验证——真实的对外支付在 8 秒内结算。

---

你可以用它做什么

• 为自己调用的付费工具付费的编码 Agent（L402 风格的付费 MCP 服务）。
• 在你设置的每日限额内，为有趣的 NOSTR 笔记发送 zap 的机器人。
• 按任务支付少量费用给其使用的工作者 Agent 的评估框架。
• 收到私信后开具收款发票的店铺 Agent。
• 了解 sats 的个人 Agent——“每周五，通过 LN 地址向我最喜欢的 OSS 维护者发送 1,000 sats。”

安全机制是让它能在生产环境中使用的关键：Agent 可以发起支付请求，但 服务端 会拒绝任何超出你所配置限额的请求；如果你启用了二次确认，则会要求进行第二步确认；此外，每次调用都会写入结构化审计日志。

---

十二个工具

只读（始终启用，无支出风险）

工具	用途
nwc_get_info	钱包功能、支持的 NIP-47 方法、节点公钥、网络、别名。请先调用。
nwc_get_balance	可支出的余额，单位为 sats（和 msat）。
nwc_lookup_invoice	按支付哈希或 bolt11 查找发票；返回状态，以及结算后的 preimage。
nwc_list_transactions	根据筛选条件列出交易（时间范围、方向、未支付）。
nwc_decode_invoice	在本地解析 bolt11——金额、备注、有效期、收款方公钥。不发起网络调用。
nwc_budget_status	当前支出预算状态——每日已支出金额、限额、累计支出金额。

收款（安全——仅生成发票，不支出）

工具	用途
nwc_make_invoice	为指定 sats 金额创建 bolt11 发票。

支出（受安全流程保护）

工具	用途
nwc_pay_invoice	支付 bolt11。可通过 amount_override_sats 为未指定金额的发票解析金额。
nwc_pay_lightning_address	支付 [email protected]（LUD-16）。直接解析 LNURL-pay，默认不经过代理。
nwc_pay_lnurl	支付原始 lnurl1... bech32 字符串（LUD-01）。
nwc_multi_pay_invoice	单次调用最多支付 20 张发票。总金额会与预算限额进行原子性检查。
nwc_pay_keysend	直接向公钥发送自发支付。默认关闭——通过 NWC_KEYSEND_ENABLED=true 启用。
nwc_confirm_payment	使用一次性令牌执行需要两步确认的支付。

---

要求

• Node 20+
• 来自兼容 NIP-47 钱包（Alby Hub、Mutiny、Coinos、Phoenix，……）的 NWC 连接字符串

标准的买家配置是使用 Alby Hub PRO，并为 Agent 配置专用子钱包——本服务已针对这种配置完成冒烟测试。不过，该协议与钱包无关；任何支持 NIP-47 的钱包都能使用。

安装

# From npm (once published)
npx -y nwc-mcp

# From source
git clone <repo>
cd nwc-mcp
corepack enable pnpm
pnpm install
pnpm build

配置

将 .env.example 复制为 .env，并填入你的 NWC 连接字符串：

cp .env.example .env
# edit .env: NWC_CONNECTION_STRING=nostr+walletconnect://...

服务会自动从当前工作目录和项目根目录（dist/ 上一级）加载 .env。父进程传入的环境变量（例如，通过 claude mcp add --env ... 传入）优先级高于 .env。.env 已加入 gitignore——请勿将 NWC 连接字符串放入任何提交的文件中。

必需项

变量	用途
NWC_CONNECTION_STRING	nostr+walletconnect://... — 从你的钱包获取（在 Alby Hub 中：子钱包 → 连接）。请视为机密 — 任何持有此字符串的人都能在每日上限内花费资金。
NWC_DAILY_BUDGET_SATS	滚动 24 小时支出上限。未设置此项时，服务拒绝启动。

可选安全设置

变量	默认值	用途
NWC_TOTAL_BUDGET_SATS	未设置	生命周期总支出上限。
NWC_MAX_INVOICE_SATS	未设置	单笔支付上限。
NWC_READ_ONLY	false	若为 true，则禁用所有支出工具 — 适用于开发 / 评估 / 好奇模式。
NWC_REQUIRE_CONFIRM	false	若为 true，支出工具会返回一次性令牌；只有使用该令牌调用 nwc_confirm_payment 后才会执行支付。以 Agent 自主性换取安全性。
NWC_KEYSEND_ENABLED	false	nwc_pay_keysend 的启用开关。默认关闭，因为 keysend 面向高级用户（没有支付哈希，安全性低于 bolt11）。
NWC_ALLOWED_DESTINATIONS	未设置	以逗号分隔的 LN 地址 / 公钥 / LNURL 允许列表。若已设置，则 ONLY 允许向其中列出的对象付款。
NWC_LOG_PATH	./nwc-mcp.log	结构化审计日志文件的路径。
NWC_BUDGET_STATE_PATH	./nwc-mcp-state.json	持久化预算跟踪器状态的路径。

---

接入 MCP 客户端

Claude Code（项目级，推荐）

在此目录中运行：

claude mcp add nwc -s project node "$(pwd)/dist/index.js"

这会在项目根目录中写入 .mcp.json。项目级服务仅在 Claude Code 从此目录树启动时加载。在会话中使用 /mcp 查看已加载的内容。重新构建后，重启 CLI 以加载最新的 dist/index.js。

如果想让服务在所有位置都可用，请将 -s project 改为 -s user。

Claude Desktop / Cursor / 其他客户端

请参阅 examples/claude-desktop-config.json 中的清单片段。将其复制到客户端配置中，并替换路径占位符。由于服务会自行加载 .env，无需通过客户端配置传入 NWC_* 变量 — 将 env 块留空即可。

---

安全模型

此服务专为持有真实 sats 支出密钥的自主大模型 Agent 而设计。每次调用支出工具时，纵深防御都会按以下顺序执行：

1. NWC_READ_ONLY 闸门 — 若已设置，则在第一道闸门处拦截。不解码、不访问网络，仅写入审计日志条目。
2. 发票解码 + 金额解析 — 适用于基于 bolt11 的工具。若金额存在歧义（覆盖金额与内嵌金额冲突），则拒绝处理。
3. 允许列表检查 — 若设置了 NWC_ALLOWED_DESTINATIONS，则收款方（bolt11 使用公钥，LUD-16 使用 LN 地址，LUD-01 使用 LNURL 字符串，keysend 使用公钥）必须匹配。空允许列表 = 不执行检查。
4. 预算检查 — 每日滚动上限 + 可选总额上限 + 可选单张发票上限。状态会持久化到 NWC_BUDGET_STATE_PATH。
5. 两步确认闸门 — 若 NWC_REQUIRE_CONFIRM=true，则返回有效期为 5 分钟的 16 字节十六进制令牌，而不执行支付。Agent 必须使用该令牌调用 nwc_confirm_payment。令牌使用时会重新执行安全检查。
6. 执行 — 通过 NIP-47 调用钱包。成功后：预算记录本金 +（向上取整后的）费用。
7. 审计日志 — 每次尝试（成功、拦截、错误）都会按每次调用一行的形式追加结构化 JSON。

最底层保障是 NWC 连接自身的每日上限，该上限在你的钱包中设置。 此服务的检查是额外的双重保障 — 即使你对服务完全不信任，钱包仍不会超出其连接级别的上限。

验证调用是否确实成功

无论大模型告诉你什么，都可以使用 tail 查看审计日志：

tail -n 5 nwc-mcp.log

成功调用：{"ts":"...","tool":"nwc_pay_invoice","outcome":"ok","result":{"paid_sats":50,...}}。遭到拦截：{"ts":"...","tool":"nwc_pay_invoice","outcome":"blocked","blocked_reason":"..."}。审计日志有意设计为仅追加；请将日志轮转纳入日常运维。

---

测试

pnpm typecheck   # tsc --noEmit
pnpm test        # 25 vitest cases covering Allowlist, ConfirmStore, evaluateSafety, decodeLnurl
pnpm build       # produces dist/index.js (~47 KB ESM bundle)

evaluateSafety 是一个纯函数，单元测试会针对完整的安全矩阵（只读 / 金额冲突 / 允许列表 / 预算 / 确认）进行测试，不会接触真实钱包。

如需针对在线钱包进行端到端冒烟测试，请参阅父项目中的 paywall-mcp-test/——这是一个临时的第二个 MCP 服务，提供一个付费工具（premium_compliment），并验证完整的 Agent → 发票 → 支付 → 兑换流程。

---

许可证

MIT——请参阅 LICENSE。

联系方式 / 问题反馈

由 LLMOps.Pro 构建。

• NOSTR： npub1hdg932jvwc3jdvkqywgqv0ue4nn60exrf92asy8mtazt3hjg7d2s2yw0nw——关注、私信、打赏。
• Lightning 地址： [email protected]——用于支持打赏和“这很有用”小费。
• 错误报告 / 功能请求： 在 GitHub 上提交 issue（https://github.com/llmops-pro/nwc-mcp）。
• 安全问题： 请先通过 NOSTR 私信私下披露，再提交公开 issue。