Nwc Mcp

io.github.llmops-proPublished by GitHub account llmops-prov0.2.3Updated Oct 24, 2026

Lightning wallet for AI agents via Nostr Wallet Connect (NIP-47): budget caps, confirm, audit log.

VerifiedSTDIODesktop onlyFinanceAI & ML

Overview

AI-generated overview

Lightning wallet MCP server that lets an AI agent read balance, create invoices and pay sats over Nostr Wallet Connect, with budget caps and an audit log.

What you can do
  • Inspect the wallet and its transactions: capabilities, balance, invoice lookup, local bolt11 decoding, budget status
  • Create receive invoices for a given amount of sats
  • Pay bolt11 invoices, Lightning Addresses, LNURL strings, and batches of up to 20 invoices
  • Send keysend payments to a pubkey, only when explicitly enabled
  • Confirm a pending payment by consuming its one-time token
  • Every spend call passes through read-only, allowlist, budget and confirmation gates and is written to a JSON audit log
When to use it
Use it when an agent should pay small amounts of real sats on its own: paying for paywalled tool calls, zapping notes, paying per-task fees, or issuing invoices to customers, while you keep spending inside limits you set.
Requirements
Runs locally as a Node.js 20+ process (npm package nwc-mcp, stdio). Needs a NWC connection string from a NIP-47 wallet such as Alby Hub, Mutiny, Coinos or Phoenix, supplied as NWC_CONNECTION_STRING; the server refuses to start without NWC_DAILY_BUDGET_SATS. Optional variables tune caps, read-only mode, confirmation, keysend, allowlist and log paths. Network access to the wallet relay is required.
Before you install
It holds a wallet connection that can spend real money: NWC_CONNECTION_STRING is a secret, and anyone holding it can spend up to the connection's daily cap. Use a dedicated sub-wallet rather than your main one. Spend tools move funds; keep NWC_DAILY_BUDGET_SATS, NWC_MAX_INVOICE_SATS and NWC_ALLOWED_DESTINATIONS set, and consider NWC_REQUIRE_CONFIRM or NWC_READ_ONLY. The audit log and budget state files are written to disk and should be kept out of version control.

Installation

In SourceWeft

  1. Open Nwc Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

nwc-mcp

A Lightning wallet for your LLM agent. MCP server that exposes Nostr Wallet Connect (NIP-47) wallet operations as tools your agent can call — read balance, generate invoices, pay invoices, pay Lightning Addresses, pay LNURLs, batch payments, keysend — all wrapped in a defense-in-depth safety stack.

Drop it into Claude Desktop, Claude Code, Cursor, or any MCP-speaking client. Hand the agent a sub-wallet (not your main one). Set a daily cap. Let it spend sats on your behalf within rails you control.

v0.2 — all spend tools shipped. Twelve tools (7 read/receive + 5 spend + 1 confirm), four safety gates, full audit log. Validated end-to-end against Alby Hub + Olympus by ZEUS routing — real outbound payment settled in 8 seconds.

What you can do with this

  • A coding agent that pays for its own paywalled tool calls (L402-style paid MCP servers).
  • A NOSTR bot that zaps interesting notes under a daily cap you set.
  • An evaluation harness that pays a small fee per task to a worker agent it consumes.
  • A storefront agent that issues receive invoices in response to incoming DMs.
  • Personal sats-aware agents — "every Friday, send 1,000 sats to my favorite OSS maintainers via their LN addresses."

The safety stack is the load-bearing reason this is usable in production: the agent can request a payment, but the server refuses anything that breaches your configured limits, demands a second-step confirmation if you set one, and writes every call to a structured audit log.

The twelve tools

Read-only (always enabled, no spend risk)

ToolPurpose
nwc_get_infoWallet capabilities, supported NIP-47 methods, node pubkey, network, alias. Call first.
nwc_get_balanceSpendable balance in sats (and msat).
nwc_lookup_invoiceLook up an invoice by payment hash or bolt11; returns state + preimage if settled.
nwc_list_transactionsList transactions with filters (time range, direction, unpaid).
nwc_decode_invoiceParse a bolt11 locally — amount, memo, expiry, payee pubkey. No network call.
nwc_budget_statusCurrent spend budget state — daily spent, caps, lifetime spent.

Receive (safe — only generates invoices, no spend)

ToolPurpose
nwc_make_invoiceCreate a bolt11 invoice for a given amount of sats.

Spend (gated by the safety pipeline)

ToolPurpose
nwc_pay_invoicePay a bolt11. Amount-resolution for amountless invoices via amount_override_sats.
nwc_pay_lightning_addressPay [email protected] (LUD-16). Direct LNURL-pay resolution, non-proxied by default.
nwc_pay_lnurlPay a raw lnurl1... bech32 string (LUD-01).
nwc_multi_pay_invoicePay up to 20 invoices in one call. Sum is checked against the budget cap atomically.
nwc_pay_keysendSpontaneous payment direct to a pubkey. Default-off — opt in via NWC_KEYSEND_ENABLED=true.
nwc_confirm_paymentExecute a two-step-confirm payment by consuming its one-time token.

Requirements

  • Node 20+
  • A NWC connection string from a NIP-47-compatible wallet (Alby Hub, Mutiny, Coinos, Phoenix, …)

The canonical buyer setup is Alby Hub PRO with a dedicated sub-wallet for the agent — that's what this server has been smoke-tested against. But the protocol is wallet-agnostic; anything that speaks NIP-47 works.

Install

bash
# From npm (once published)npx -y nwc-mcp
# From sourcegit clone <repo>cd nwc-mcpcorepack enable pnpmpnpm installpnpm build

Configure

Copy .env.example to .env and fill in your NWC connection string:

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

The server auto-loads .env from the current working directory and from the project root (one level up from dist/). Env vars passed by the parent process (e.g., claude mcp add --env ...) take precedence over .env. .env is gitignored — keep your NWC string out of any committed file.

Required

VarPurpose
NWC_CONNECTION_STRINGnostr+walletconnect://... — get this from your wallet (in Alby Hub: Sub-wallets → Connections). Treat as a secret — anyone holding it can spend up to the daily cap.
NWC_DAILY_BUDGET_SATSRolling 24h spend cap. Server refuses to start without this set.

Optional safety knobs

VarDefaultPurpose
NWC_TOTAL_BUDGET_SATSunsetLifetime spend cap.
NWC_MAX_INVOICE_SATSunsetPer-payment cap.
NWC_READ_ONLYfalseIf true, disables all spend tools — useful for dev / eval / curious mode.
NWC_REQUIRE_CONFIRMfalseIf true, spend tools return a one-time token; payment only executes after nwc_confirm_payment with the token. Trades agent autonomy for safety.
NWC_KEYSEND_ENABLEDfalseOpt-in toggle for nwc_pay_keysend. Off because keysend is power-user (no payment hash, weaker safety surface than bolt11).
NWC_ALLOWED_DESTINATIONSunsetComma-separated allowlist of LN addresses / pubkeys / LNURLs. If set, ONLY those can be paid.
NWC_LOG_PATH./nwc-mcp.logPath to the structured audit log file.
NWC_BUDGET_STATE_PATH./nwc-mcp-state.jsonPath to the persisted budget tracker state.

Wire into an MCP client

Claude Code (project-scoped, recommended)

From this directory:

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

This writes a .mcp.json in the project root. Project-scoped servers load only when Claude Code starts from this directory tree. Use /mcp inside a session to inspect what's loaded. Restart the CLI to pick up a fresh dist/index.js after a rebuild.

Switch -s project to -s user if you want the server available everywhere.

Claude Desktop / Cursor / other clients

See examples/claude-desktop-config.json for the manifest snippet. Copy it into your client's config, replace the path placeholder. Because the server loads .env itself, you don't need to pass NWC_* vars through the client config — leave the env block empty.

Safety model

This server is designed for use by autonomous LLM agents that hold the keys to spend real sats. The defense in depth runs in this order on every spend tool call:

  1. NWC_READ_ONLY gate — if set, blocks at the first gate. No decode, no network, audit log entry only.
  2. Invoice decode + amount resolution — for bolt11-based tools. Rejects ambiguity (amount-override conflicting with embedded amount).
  3. Allowlist check — if NWC_ALLOWED_DESTINATIONS is set, the payee (pubkey for bolt11, LN address for LUD-16, LNURL string for LUD-01, pubkey for keysend) must match. Empty allowlist = no-op.
  4. Budget check — daily rolling cap + optional total cap + optional per-invoice cap. State is persisted to NWC_BUDGET_STATE_PATH.
  5. Two-step confirmation gate — if NWC_REQUIRE_CONFIRM=true, returns a 16-byte hex token with 5-minute TTL instead of executing. Agent must call nwc_confirm_payment with the token. Safety re-runs on consume.
  6. Execute — calls the wallet via NIP-47. On success: budget records principal + (over-rounded) fees.
  7. Audit log — every attempt (success, blocked, error) is appended as one structured JSON line per call.

The floor is your NWC connection's own daily cap, set in your wallet. This server's checks are belt-and-suspenders on top — if you trust nothing about the server, the wallet still won't spend past its connection-level cap.

Verifying calls actually went through

Independent of what the LLM tells you, tail the audit log:

bash
tail -n 5 nwc-mcp.log

Successful call: {"ts":"...","tool":"nwc_pay_invoice","outcome":"ok","result":{"paid_sats":50,...}}. Blocked: {"ts":"...","tool":"nwc_pay_invoice","outcome":"blocked","blocked_reason":"..."}. The audit log is append-only by intent; rotate it as part of your operational hygiene.

Testing

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

evaluateSafety is a pure function that the unit tests exercise across the full safety matrix (read-only / amount-conflict / allowlist / budget / confirm) without touching a real wallet.

For end-to-end smoke testing against a live wallet, see paywall-mcp-test/ in the parent project — a throwaway second MCP server that exposes one paid tool (premium_compliment) and validates the full agent → invoice → pay → redeem loop.

License

MIT — see LICENSE.

Contact / Issues

Built by LLMOps.Pro.

Source: README.md at commit d405e54

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.3LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts