# Lightning Wallet MCP server

> Enables AI agents to manage a Bitcoin wallet, pay Lightning invoices, handle L402/X402 API payments, and participate in prediction markets.

- Repository: https://github.com/lightningfaucet/mcp-server
- Page: https://hostedmcp.org/servers/lightningfaucet/mcp-server
- Transport: stdio
- Stars: 11
- License: MIT
- Latest version: 2.0.5

## Install

### Claude Code

```sh
claude mcp add mcp-server -- npx -y lightning-faucet-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "lightning-faucet-mcp"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "lightning-faucet-mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"mcp-server","type":"stdio","command":"npx","args":["-y","lightning-faucet-mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "lightning-faucet-mcp"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add mcp-server -- npx -y lightning-faucet-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.mcp-server]
command = "npx"
args = ["-y", "lightning-faucet-mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user mcp-server npx -- -y lightning-faucet-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "lightning-faucet-mcp"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `LIGHTNING_WALLET_API_KEY` | no | no |  |

## Tools (37)

- `check_balance`: Check your current Lightning balance in satoshis. Works with both operator and agent keys.
- `pay_l402_api`: Make a request to an L402-protected API. If payment is required (HTTP 402), automatically pay the Lightning invoice and complete the request. REQUIRES AGENT KEY - use set_agent_credentials first if operating as an operator.
- `pay_invoice`: Pay a BOLT11 Lightning invoice from the agent balance. Returns preimage as proof of payment. REQUIRES AGENT KEY.
- `create_invoice`: Create a Lightning invoice to receive payment. Use get_invoice_status to check if paid.
- `get_invoice_status`: Check if a created invoice has been paid. Use the payment_hash from create_invoice.
- `get_transactions`: Get the agent transaction history. Returns both incoming and outgoing payments.
- `register_operator`: Register a new operator account. Returns API key and recovery code. SAVE THESE - they cannot be retrieved later!
- `get_deposit_invoice`: Create a Lightning invoice to fund your operator account. Pay this invoice to add sats to your balance.
- `create_agent`: Create a new agent under your operator account. Returns the agent API key.
- `fund_agent`: Transfer sats from operator balance to an agent.
- `list_agents`: List all agents under your operator account.
- `set_operator_key`: Switch to a different operator API key for subsequent requests. Use after register_operator to start using the new credentials.
- `set_agent_credentials`: Switch to an agent API key for subsequent requests. Use to operate as a specific agent after creating it.
- `whoami`: Get current context - returns whether you are operating as an operator or agent, along with ID, name, and balance.
- `register_webhook`: Register a webhook URL to receive payment notifications. Max 5 webhooks per agent. REQUIRES AGENT KEY.
- `list_webhooks`: List all registered webhooks for the current agent. REQUIRES AGENT KEY.
- `delete_webhook`: Delete a registered webhook. REQUIRES AGENT KEY.
- `test_webhook`: Send a test event to a webhook to verify it works. REQUIRES AGENT KEY.
- `get_budget_status`: Get budget status for an agent - shows limit, spent, and remaining. Works with operator or agent keys.
- `set_budget`: Set or update budget limit for an agent. REQUIRES OPERATOR KEY.
- `deactivate_agent`: Deactivate an agent - it cannot make payments until reactivated. REQUIRES OPERATOR KEY.
- `reactivate_agent`: Reactivate a previously deactivated agent. REQUIRES OPERATOR KEY.
- `recover_account`: Recover an operator account using the recovery code from registration. Returns a new API key. Triggers 60-min withdrawal cooldown.
- `rotate_api_key`: Generate a new API key, invalidating the old one. For operators: triggers 60-min withdrawal cooldown. For agents: 30-min cooldown.
- `get_info`: Get service information including version, status, limits, and supported features.
- `decode_invoice`: Decode a BOLT11 invoice without paying it. Returns amount, description, expiry, and destination.
- `get_rate_limits`: Get current rate limit status - requests remaining and reset time.
- `withdraw`: Withdraw funds from operator account to external Lightning invoice. REQUIRES OPERATOR KEY. Subject to security cooldown.
- `sweep_agent`: Sweep funds from agent back to operator balance. REQUIRES OPERATOR KEY.
- `pay_lightning_address`: Pay to a Lightning address (user@domain.com format). REQUIRES AGENT KEY.
- `export_transactions`: Export transaction history in JSON or CSV format.
- `get_agent_analytics`: Get detailed spending analytics for an agent.
- `transfer_to_agent`: Transfer sats between agents or from operator to agent. REQUIRES OPERATOR KEY.
- `delete_agent`: Permanently delete an agent. Remaining balance is returned to operator. REQUIRES OPERATOR KEY.
- `lnurl_auth`: Authenticate to a service using LNURL-auth protocol. REQUIRES AGENT KEY.
- `claim_lnurl_withdraw`: Claim funds from an LNURL-withdraw link. REQUIRES AGENT KEY.
- `keysend`: Send a payment directly to a node without an invoice (keysend/spontaneous payment). REQUIRES AGENT KEY.

## FAQ

### Do I need to run my own Bitcoin node?

No, the service is custodial, meaning there is no need to manage a node, channels, or liquidity.

### How can I fund my agent's wallet?

You can request a deposit invoice using the `get_deposit_invoice` tool and pay it from any Lightning wallet.
