MCP Server

What lightningfaucet/mcp-server does

lightningfaucet/mcp-server connects an MCP host to the Lightning Faucet custodial wallet service. It gives an AI agent a wallet context that can hold satoshis, make Lightning payments, receive funds, and inspect account activity. The service handles the wallet infrastructure, so the deployment does not require a Lightning node, channels, or independently managed liquidity.

The server can pay a BOLT11 invoice, a Lightning address, or a node public key using keysend. It also supports NIP-57 Nostr zaps, LNURL-auth, and LNURL-withdraw claims. For HTTP services that answer with status 402, pay_l402_api detects L402 Lightning or X402 USDC-on-Base payment requirements and attempts payment before requesting the API.

How it works

MCP tools run through a local stdio process started with the lightning-wallet-mcp npm package. The server uses an operator API key or an agent key to identify the current wallet context. When no environment key is supplied, credentials saved locally by supported account tools are loaded on startup.

Operator-level payments can use the operator key directly. Optional agents provide separate keys and spending budgets; the operator can create them, fund them, list them, and sweep funds back. Payment calls can report a pending state while an in-flight payment settles, so callers should not automatically retry a payment that may have completed.

Setup and configuration

Install the server through an MCP host with npx:

{
  "mcpServers": {
    "lightning-wallet": {
      "command": "npx",
      "args": ["-y", "lightning-wallet-mcp"]
    }
  }
}

Claude Code can add the same server with claude mcp add lightning-wallet -- npx -y lightning-wallet-mcp. Cursor and Windsurf can use their MCP configuration files. An existing operator key can be supplied as LIGHTNING_WALLET_API_KEY; this takes precedence over the saved credentials file. Account registration saves credentials under ~/.lightning-wallet/credentials.json with restrictive file permissions. Set LIGHTNING_WALLET_NO_PERSIST=1 to disable credential writes.

Tools and capabilities

lightningfaucet/mcp-server includes unauthenticated service inspection and invoice decoding through get_info and decode_invoice. Identity, balance, rate-limit, transaction, and invoice-status tools help an agent inspect its wallet state.

Payment and funding capabilities include:

• Pay invoices, Lightning addresses, node keys, Nostr users, and Nostr events.
• Request L402 or X402 APIs through automatic payment handling.
• Create receiving invoices and deposit invoices.
• Withdraw to an external invoice or create an LNURL-withdraw link.
• Claim LNURL-withdraw funds and authenticate with LNURL-auth.
• Register or update an operator, rotate or recover credentials, and switch keys.
• Create agents, assign budgets, fund them, and sweep their balances.

Limitations and notes

The wallet is custodial and depends on the Lightning Faucet service. The material does not describe self-hosted node operation or local channel management. Withdrawals require at least 10 sats. Rotating an API key pauses payments for 60 minutes. Credential persistence is enabled by default unless disabled with the documented environment variable, so deployments should protect the local credentials file and API key.

The server can use the operator context directly, while agent contexts are useful when separate budgets or balances are required. Calls that return pending: true need status-aware handling rather than immediate retries.