nwc-mcp

nwc-mcp

LLM エージェントのための Lightning ウォレットです。 エージェントが呼び出せるツールとして、Nostr Wallet Connect（NIP-47）のウォレット操作を提供する MCP サーバーです。残高の確認、インボイスの生成、インボイスの支払い、Lightning アドレスへの支払い、LNURL への支払い、一括支払い、keysend に対応しており、すべて多層防御の安全性スタックで保護されています。

Claude Desktop、Claude Code、Cursor、または MCP に対応した任意のクライアントに追加できます。エージェントにはメインウォレットではなく、サブウォレットを渡してください。1 日の上限を設定すれば、管理下の制限内でエージェントに sats を使わせることができます。

v0.2 — すべての支払いツールをリリースしました。 12 個のツール（読み取り／受け取り 7 個＋支払い 5 個＋確認 1 個）、4 つの安全性ゲート、完全な監査ログを備えています。Alby Hub と Olympus を ZEUS ルーティングで使ってエンドツーエンドで検証済みです。実際の送金は 8 秒で決済されました。

---

これでできること

• 有料のツール呼び出し（L402 形式の有料 MCP サーバー）を自分で支払うコーディングエージェント。
• 設定した 1 日の上限内で、興味深い投稿に zap を送る NOSTR ボット。
• 利用するワーカーエージェントに、タスクごとの少額手数料を支払う評価ハーネス。
• 受信 DM への返信として受け取り用インボイスを発行するストアフロントエージェント。
• sats を扱うパーソナルエージェント —「毎週金曜日に、お気に入りの OSS メンテナーへ LN アドレス経由で 1,000 sats を送る。」

この安全性スタックがあるからこそ、本番環境でも安心して利用できます。エージェントは支払いを要求できますが、設定した制限に違反する支払いはサーバーが拒否し、設定されている場合は 2 段階目の確認を求め、すべての呼び出しを構造化された監査ログに記録します。

---

12 個のツール

読み取り専用（常時有効、支払いリスクなし）

ツール	用途
nwc_get_info	ウォレットの機能、対応する NIP-47 メソッド、ノードの公開鍵、ネットワーク、エイリアスを取得します。最初に呼び出してください。
nwc_get_balance	支払い可能な残高を sats（および msat）で取得します。
nwc_lookup_invoice	支払いハッシュまたは bolt11 でインボイスを検索し、状態と、決済済みの場合はプリイメージを返します。
nwc_list_transactions	フィルター（期間、方向、未払い）を指定して取引を一覧表示します。
nwc_decode_invoice	bolt11 をローカルで解析します。金額、メモ、有効期限、受取人の公開鍵を取得します。ネットワーク呼び出しはありません。
nwc_budget_status	現在の支払い予算の状態を取得します。1 日の支払い額、上限、累計支払い額を確認できます。

受け取り（安全 — インボイスを生成するだけで、支払いは発生しません）

ツール	用途
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	1 回の呼び出しで最大 20 件のインボイスに支払います。合計額が予算上限を超えないか、アトミックに確認されます。
nwc_pay_keysend	公開鍵宛てに自発的な支払いを行います。デフォルトでは無効 — NWC_KEYSEND_ENABLED=true で有効にできます。
nwc_confirm_payment	1 回限りのトークンを使用して、2 段階確認が必要な支払いを実行します。

---

必要条件

• Node 20 以上
• NIP-47 対応ウォレット（Alby Hub、Mutiny、Coinos、Phoenix など）の NWC 接続文字列

標準的な購入者向けセットアップでは、エージェント専用のサブウォレットを備えた Alby Hub PRO を使用します。このサーバーは Alby Hub PRO でスモークテスト済みです。ただし、このプロトコルは特定のウォレットに依存しません。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/ の 1 つ上の階層）から .env を自動的に読み込みます。親プロセスから渡された環境変数（例：claude mcp add --env ...）は .env より優先されます。.env は Git の追跡対象外です。コミットするファイルに NWC 文字列を含めないでください。

必須

変数	用途
NWC_CONNECTION_STRING	nostr+walletconnect://... — ウォレットから取得します（Alby Hub の場合：Sub-wallets → Connections）。秘密情報として扱ってください。この値を持つ人は誰でも、1 日の上限額まで支出できます。
NWC_DAILY_BUDGET_SATS	24 時間単位のローリング支出上限です。これが設定されていないと、サーバーは起動しません。

任意の安全設定

変数	デフォルト	用途
NWC_TOTAL_BUDGET_SATS	未設定	生涯支出上限です。
NWC_MAX_INVOICE_SATS	未設定	1 回の支払いあたりの上限です。
NWC_READ_ONLY	false	true の場合、すべての支出ツールを無効にします。開発／評価／動作確認モードに便利です。
NWC_REQUIRE_CONFIRM	false	true の場合、支出ツールはワンタイムトークンを返し、トークンを指定して nwc_confirm_payment を呼び出した後にのみ支払いが実行されます。エージェントの自律性を犠牲にして安全性を高めます。
NWC_KEYSEND_ENABLED	false	nwc_pay_keysend を有効にするオプトイン設定です。Keysend はパワーユーザー向けであり（支払いハッシュがなく、bolt11 より安全性が低いため）、デフォルトでは無効です。
NWC_ALLOWED_DESTINATIONS	未設定	LN アドレス／公開鍵／LNURL の許可リストをカンマ区切りで指定します。設定すると、指定した宛先にのみ支払いが可能になります。
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 を使うと、読み込まれている内容を確認できます。再ビルド後に新しい dist/index.js を読み込むには、CLI を再起動してください。

サーバーをどこからでも使えるようにするには、-s project を -s user に切り替えてください。

Claude Desktop／Cursor／その他のクライアント

マニフェストの例については、examples/claude-desktop-config.json を参照してください。これをクライアントの設定にコピーし、パスのプレースホルダーを置き換えます。サーバーは .env を自ら読み込むため、クライアント設定を通じて NWC_* 変数を渡す必要はありません。env ブロックは空のままにしてください。

---

安全性モデル

このサーバーは、実際の sats を支出する鍵を持つ自律型 LLM エージェントによる使用を想定して設計されています。すべての支出ツール呼び出しで、多層防御が次の順に実行されます。

1. NWC_READ_ONLY ゲート — 設定されている場合、最初のゲートでブロックします。デコードもネットワーク通信も行わず、監査ログへの記録のみを行います。
2. インボイスのデコードと金額の解決 — bolt11 ベースのツールに適用されます。金額の上書きが埋め込み済みの金額と競合するなど、曖昧さがある場合は拒否します。
3. 許可リストの確認 — NWC_ALLOWED_DESTINATIONS が設定されている場合、支払先（bolt11 の公開鍵、LUD-16 の LN アドレス、LUD-01 の LNURL 文字列、keysend の公開鍵）が一致する必要があります。許可リストが空の場合は何も行いません。
4. 予算の確認 — 1 日単位のローリング上限に加え、任意で総額上限と 1 インボイスあたりの上限を適用します。状態は NWC_BUDGET_STATE_PATH に永続化されます。
5. 二段階確認ゲート — NWC_REQUIRE_CONFIRM=true の場合、実行せずに、有効期限 5 分の 16 バイトの 16 進トークンを返します。エージェントはトークンを指定して nwc_confirm_payment を呼び出す必要があります。トークンの消費時にも安全性の確認を再実行します。
6. 実行 — NIP-47 経由でウォレットを呼び出します。成功時には、元金と（切り上げ分を含む）手数料を予算に記録します。
7. 監査ログ — 成功、ブロック、エラーを問わず、呼び出しごとに構造化 JSON を 1 行追加します。

最低限の上限は、ウォレットで設定した NWC 接続自体の日次上限です。 このサーバーのチェックは、その上に重ねる多重の安全策です。サーバーの安全性をまったく信用しない場合でも、ウォレットは接続単位の上限を超えて支出しません。

呼び出しが実際に実行されたことを確認する

LLM の報告とは独立して、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/ をご覧ください。これは、1つの有料ツール（premium_compliment）を公開し、エージェント → 請求書 → 支払い → 引き換えの一連の処理を検証する、一時的な2つ目の MCP サーバーです。

---

ライセンス

MIT — LICENSE をご覧ください。

お問い合わせ／問題の報告

LLMOps.Pro が開発しました。

• NOSTR： npub1hdg932jvwc3jdvkqywgqv0ue4nn60exrf92asy8mtazt3hjg7d2s2yw0nw — フォロー、DM、投げ銭をどうぞ。
• Lightning アドレス： [email protected] — サポートへの投げ銭や、「役に立った」という感謝のチップをお送りいただけます。
• バグ報告／機能リクエスト： GitHub issue を作成してください（https://github.com/llmops-pro/nwc-mcp）。
• セキュリティ上の問題： 公開 issue を作成する前に、NOSTR DM で非公開にてご報告ください。