# lightningfaucet/mcp-server [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/lightningfaucet/mcp-server  
**GitHub Stars:** 10  
**npm Downloads (last month):** 915  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-server-134

## Description
Give AI agents a Bitcoin wallet with Lightning Network payments and L402 support.

## Tools
Capabilities this server exposes over MCP:

- **get_info** — Service status, version and supported features (no key needed)
- **decode_invoice** — Decode a BOLT11 invoice: amount, destination, expiry (no key needed)
- **whoami** — Current identity (operator or agent), balance, where the key came from
- **check_balance** — Balance in sats
- **get_rate_limits** — Rate-limit status and requests remaining
- **forget_credentials** — Delete the saved credentials file
- **pay_l402_api** — Request a paid API. Detects L402 (Lightning) or X402 (USDC on Base) on HTTP 402 and pays automatically
- **pay_invoice** — Pay any BOLT11 invoice; returns the preimage
- **pay_lightning_address** — Pay `user@domain
- **keysend** — Pay a node pubkey directly, with an optional message
- **nostr_zap** — NIP-57 zap to a Nostr user or event
- **lnurl_auth** — Log in to a service with LNURL-auth
- **claim_lnurl_withdraw** — Pull funds from an LNURL-withdraw link
- **create_invoice** — Invoice to receive sats
- **get_invoice_status** — Has an invoice been paid
- **get_deposit_invoice** — Invoice to fund the operator account
- **get_transactions** — Transaction history
- **set_nostr_identity** — Nostr keypair for the agent
- **register_operator** — Create an account; credentials are saved locally
- **update_operator** — Set email (sends a verification link) or display name
- **claim_promo** — Claim the install promo manually (it is also granted automatically after verification)
- **withdraw** — Withdraw to an external invoice (minimum 10 sats)
- **create_withdraw_link** — LNURL-withdraw link to sweep into any wallet by QR
- **recover_account** — Recover with the recovery code (rotates the key)
- **rotate_api_key** — New key; payments pause for 60 minutes
- **set_operator_key** — Switch context and save the key
- **create_agent** — Agent with its own key and optional budget
- **list_agents** — Agents under this operator
- **fund_agent** — Move sats to an agent
- **sweep_agent** — Move sats back to the operator (`amount_sats: "all"` for everything)
- **get_budget_status** — Read or set a spending limit (0 = unlimited)
- **deactivate_agent** — Lifecycle

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-server": {
    "command": "npx",
    "args": ["-y","lightning-wallet-mcp"],
    "env": {
      "LIGHTNING_WALLET_API_KEY": "",
      "LIGHTNING_WALLET_NO_PERSIST": ""
    }
  }
}
```

**Requires environment variables:** `LIGHTNING_WALLET_API_KEY`, `LIGHTNING_WALLET_NO_PERSIST` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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`:

```json
{
  "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.

_Full upstream README: https://allmcps.com/mcp/mcp-server-134/readme_