paywall-mcp

paywall-mcp

通过 Lightning 为任何 stdio MCP 服务添加付费墙，无需修改服务本身。 paywall-mcp 是一个通用的 sidecar：配置上游 MCP 服务命令和每个工具的价格映射后，它会透明地：

• 将上游的 tools/list 转发给大模型客户端，并在每个工具的描述中附加价格。
• 拦截 tools/call：免费工具直接放行；付费工具必须先支付 Lightning 发票（通过 Nostr Wallet Connect / NIP-47），之后才会转发调用。

无需修改上游服务的代码。适用于 Anthropic 的参考 MCP 服务、自建服务，以及任何使用 stdio 通信的第三方 MCP 服务。

v0.1 — 代理和支付门控已完成。 将 stdio 上游作为子进程启动；通过环境变量设置每个工具的价格；提供内存发票缓存和防重放保护、审计日志以及只读模式。持久化缓存和 HTTP/SSE 上游传输推迟到 v0.2。

---

为什么需要它

Lightning 付费墙、L402 和小额支付等现代付费 API 模式已应用于 HTTP，但 MCP 生态系统尚无针对付费工具调用的标准。在每个独立服务中分别实现这些功能既重复又容易出错。paywall-mcp 正是缺少的 sidecar：像编写普通 MCP 服务一样编写工具，再用 paywall-mcp 包装，即可按调用次数收取 sats。

双重调用模式的工作方式

对于任何定价工具：

1. 首次调用 — 大模型调用 priced_tool({...args})，不带 payment_hash。paywall-mcp 通过你的 NWC 钱包开具 bolt11 发票，并返回：

   {
     "error": "payment_required",
     "invoice": "lnbc...",
     "payment_hash": "abc123...",
     "amount_sats": 21,
     "expires_in_seconds": 600,
     "next_step": "Pay this bolt11 ..."
   }
   

2. 支付 — 大模型（或其操作者）支付发票。最简单的方式是使用 nwc-mcp — 同一个大模型可以调用 nwc_pay_invoice 完成支付。
3. 第二次调用 — 大模型调用 priced_tool({...args, payment_hash: "abc123..."})。paywall-mcp 通过 NWC lookup_invoice 验证支付是否完成，移除参数中的 payment_hash，将原始调用转发给上游，并返回上游的结果。

防重放保护：同一个 payment_hash 不能兑换两次。购买者每次调用都必须支付一张新发票。

---

可以用它构建什么

• 为现有 MCP 服务中的高级工具收取 sats，只需添加一个包装进程。
• 为每个工具设置不同的价格档位 — free_lookup: 0、premium_analysis: 100、rare_alpha_signal: 5000。购买者可以在工具描述中看到价格。
• 捆绑并转售第三方 MCP 服务 — 用你的付费墙包装他人的开源 MCP 服务，并将其作为托管付费服务提供。
• 进行 A/B 定价测试 — 调整环境变量中的 PAYWALL_PRICE_MAP 并重启，即可应用新价格。
• 推出限时促销价 — 初始定价为 21 sats，确认价值后再提高到 100 sats。

---

要求

• Node 20+
• 一个现有的 stdio MCP 服务，用于被包装（paywall-mcp 本身不托管工具；它负责管理上游工具的访问）。
• 卖家收款钱包的 NIP-47 NWC 连接字符串。paywall-mcp 只需要 make_invoice 和 lookup_invoice 权限。仅接收款项的 NWC 连接完全可用，且推荐使用 — paywall-mcp 从不付款。

安装

# From npm
npx -y paywall-mcp

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

配置

cp .env.example .env
# edit .env: set PAYWALL_UPSTREAM_COMMAND/ARGS, NWC_CONNECTION_STRING, prices

服务会从其自身目录（dist/ 所在目录）自动加载 .env — 特意不从当前工作目录加载，以避免在同一个 Claude Code 会话中运行多个 MCP 服务时出现环境变量冲突。

必填

变量	用途
PAYWALL_UPSTREAM_COMMAND	要作为上游 MCP 服务启动的可执行文件（例如 node）。
PAYWALL_UPSTREAM_ARGS	传递给上游命令的参数 JSON 数组（例如 ["/path/to/upstream/dist/index.js"]）。

任何工具的价格非零时必填

变量	用途
NWC_CONNECTION_STRING	卖家收款钱包的 NIP-47 NWC URI。具备 make_invoice 和 lookup_invoice 权限即可。paywall-mcp 从不付款。

定价

Var	默认值	用途
PAYWALL_DEFAULT_PRICE_SATS	0	价格映射中未列出的任何工具的默认价格。0 = 免费直通。
PAYWALL_PRICE_MAP	{}	将工具名称映射到 sat 价格的 JSON 对象。每个工具的价格为 0 = 免费；未列出 = 使用默认值。示例：{"premium_compliment":21,"rare_alpha_signal":5000}。

可选项

Var	默认值	用途
PAYWALL_UPSTREAM_CWD	(父进程的工作目录)	上游子进程的工作目录。
PAYWALL_UPSTREAM_ENV	(继承)	用于覆盖上游环境变量的 JSON 对象。
PAYWALL_READ_ONLY	false	禁用所有付费工具调用（tools/list 仍可使用）。适用于维护期间。
PAYWALL_INVOICE_TTL_SECONDS	600	发票的 TTL。超过此时间后，缓存会忘记 payment_hash，买家必须重新发起请求。
PAYWALL_PRICE_LABEL_TEMPLATE	"(💰 {price} sats)"	添加到 tools/list 中每个定价工具描述末尾的标签。{price} 会替换为 sat 数量。
PAYWALL_LOG_PATH	./paywall-mcp.log	服务日志。
PAYWALL_AUDIT_PATH	./paywall-mcp-audit.log	NDJSON 审计日志（每次调用一行）。

---

端到端示例：为捆绑的 paywall-mcp-test 服务设置付费墙

配套的 paywall-mcp-test 软件包提供了一个工具 — premium_compliment。它已在内部实现自己的付费墙模式，同时也可作为“任意上游 MCP 服务”的便捷替代品，用来演示 paywall-mcp 本身。

.env：

PAYWALL_UPSTREAM_COMMAND=node
PAYWALL_UPSTREAM_ARGS=["/abs/path/to/paywall-mcp-test/dist/index.js"]

NWC_CONNECTION_STRING=nostr+walletconnect://...

PAYWALL_DEFAULT_PRICE_SATS=21
PAYWALL_PRICE_MAP={"premium_compliment":21}

将 paywall-mcp（而非直接连接上游服务）接入你的 MCP 客户端：

{
  "mcpServers": {
    "paywall": {
      "command": "npx",
      "args": ["-y", "paywall-mcp"],
      "env": {}
    }
  }
}

现在，在你的 Agent 中：

1. tools/list  → premium_compliment ... (💰 21 sats) This tool requires ...
2. premium_compliment({})  → returns invoice + payment_hash
3. nwc_pay_invoice(invoice)  → buyer pays
4. premium_compliment({ payment_hash: "..." })  → upstream's result returned

---

安全模型

tools/list      → upstream.listTools() → augment descriptions with prices → return
tools/call:
  if price == 0           → upstream.callTool(args)                  (passthrough)
  elif PAYWALL_READ_ONLY  → refuse with paywall_read_only            (block)
  elif no payment_hash    → gate.issue() → return bolt11 + hash      (issue)
  elif bad hash format    → refuse with invalid_payment_hash         (block)
  else (have hash):
      gate.verify() ──┬─ unknown_payment_hash         → block
                      ├─ payment_hash_already_redeemed → block (replay)
                      ├─ payment_hash_tool_mismatch    → block
                      ├─ payment_not_settled           → block
                      └─ ok → strip hash → upstream.callTool()      (paid passthrough)

审计日志条目（NDJSON，每个请求一条）：

• outcome: "ok" — 已开具发票、免费直通或付费直通已完成
• outcome: "blocked" — 只读拒绝、哈希无效、重放、内容不匹配或未结算
• outcome: "error" — 上游调用失败、NWC lookup_invoice 失败等

查看审计日志末尾，以获取实际情况的依据 — 不受大模型告知内容的影响。

tail -f paywall-mcp-audit.log | jq .

---

接入 Claude Desktop / Claude Code / Cursor

{
  "mcpServers": {
    "paywall": {
      "command": "npx",
      "args": ["-y", "paywall-mcp"],
      "env": {}
    }
  }
}

与其他基底组件一样，使用 .env 随二进制文件所在目录加载的模式 — 客户端配置中的 env 留空；密钥保存在 paywall-mcp/.env 中。

---

测试

pnpm typecheck
pnpm test        # 13 vitest cases (config resolution + payment-gate state machine)
pnpm build       # ~18 KB ESM bundle

---

配套服务

• nwc-mcp — 面向买家的 Lightning 钱包。让 Agent 能够支付 paywall-mcp 开具的发票，是 Agent 支付付费工具这一流程的配套部分。
• nostr-ops-mcp — NOSTR 身份、发布和加密私信。
• marketplace-mcp — 通过 Agent 运行 NIP-15 / Shopstr 店面。
• albyhub-admin-mcp — 通过 HTTP API 管理 Alby Hub 节点。

---

许可证

MIT — 参见 LICENSE。

联系方式 / 问题反馈

由 LLMOps.Pro 构建。

• NOSTR： npub1hdg932jvwc3jdvkqywgqv0ue4nn60exrf92asy8mtazt3hjg7d2s2yw0nw — 关注、私信、打赏。
• Lightning 地址： [email protected] — 用于支持打赏和“这很有用”的小费。
• 错误报告 / 功能请求： 提交 GitHub issue（链接即将提供）。
• 安全问题： 请先通过 NOSTR 私信私下披露，再提交公开 issue。