Lightning Enable MCP - Complete Guide

The Lightning Enable MCP (Model Context Protocol) server enables AI agents to interact with the Lightning Network. It's free for personal use and provides comprehensive Lightning wallet capabilities.

Overview

┌─────────────────────────────────────────────────────────────────┐
│                    Lightning Enable MCP                          │
├─────────────────────────────────────────────────────────────────┤
│  AI Agent (Claude, etc.)                                         │
│       ↓                                                          │
│  MCP Server                                                      │
│       ↓                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐           │
│  │   Strike     │  │   OpenNode   │  │     NWC      │           │
│  │   Wallet     │  │   Wallet     │  │   Wallet     │           │
│  └──────────────┘  └──────────────┘  └──────────────┘           │
│       ↓                    ↓                ↓                    │
│  Lightning Network                                               │
└─────────────────────────────────────────────────────────────────┘

Installation

.NET (Windows, Linux, macOS)

dotnet tool install -g LightningEnable.Mcp

Python (All Platforms)

pip install lightning-enable-mcp

Or use uvx for no-install execution:

uvx lightning-enable-mcp

Quick Start

Add to your Claude Desktop config:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "lightning-enable": {
      "command": "dotnet",
      "args": ["tool", "run", "lightning-enable-mcp"],
      "env": {
        "STRIKE_API_KEY": "your-strike-api-key"
      }
    }
  }
}

---

All Available Tools

Tool Availability by Wallet

Tool	Strike	OpenNode	NWC (Alby/CoinOS)	NWC (Primal)	License
pay_invoice	✅	✅	✅	✅	FREE
check_wallet_balance	✅	✅	✅	✅	FREE
get_payment_history	✅	✅	✅	✅	FREE
get_budget_status	✅	✅	✅	✅	FREE
create_invoice	✅	✅	✅*	✅*	FREE
check_invoice_status	✅	✅	❌	❌	FREE
get_all_balances	✅	✅	✅	✅	FREE
get_btc_price	✅	❌	❌	❌	FREE
exchange_currency	✅	❌	❌	❌	FREE
send_onchain	✅	❌	❌	❌	FREE
unlock_l402_features	✅	✅	✅	✅	FREE
check_l402_license	✅	✅	✅	✅	FREE
access_l402_resource	❌	❌	✅	❌	L402 License
pay_l402_challenge	❌	❌	✅	❌	L402 License

*NWC invoice creation depends on wallet support Primal doesn't return preimages yet, so L402 doesn't work

---

Core Tools (All Wallets)

pay_invoice

Pay any Lightning invoice and get the preimage as proof of payment.

Parameters:

Parameter	Type	Required	Default	Description
invoice	string	Yes	-	BOLT11 Lightning invoice
maxSats	int	No	1000	Maximum payment allowed

Example:

User: Pay this invoice: lnbc500n1p3...

Claude: [Uses pay_invoice]

Payment successful!
- Amount: 500 sats
- Preimage: 7f8a9b2c3d4e5f...
- Provider: Strike

Response:

{
  "success": true,
  "provider": "Strike",
  "payment": {
    "preimage": "7f8a9b2c3d4e5f...",
    "amountSats": 500
  },
  "message": "Payment successful! Paid 500 sats."
}

---

check_wallet_balance

Check your connected wallet balance.

Parameters: None required

Example:

User: What's my wallet balance?

Claude: [Uses check_wallet_balance]

Wallet Balance: 50,000 sats (~$50 USD)
Provider: Strike

Response:

{
  "success": true,
  "provider": "Strike",
  "balance": {
    "sats": 50000,
    "btc": 0.0005
  },
  "message": "Balance: 50,000 sats"
}

---

get_payment_history

View recent Lightning payments made through the MCP.

Parameters:

Parameter	Type	Required	Default	Description
limit	int	No	10	Maximum payments to return

Example:

User: Show my recent payments

Claude: [Uses get_payment_history]

Recent Payments:
1. 500 sats - lnbc500n1... - 5 min ago
2. 100 sats - lnbc100n1... - 1 hour ago
3. 1000 sats - lnbc1u1... - 2 hours ago

Total: 1,600 sats across 3 payments

---

get_budget_status

View current budget configuration and session spending. This is read-only - budget limits can only be changed by editing the config file.

Parameters: None required

Example:

User: What are my spending limits?

Claude: [Uses get_budget_status]

Budget Configuration (READ-ONLY):
- Config file: ~/.lightning-enable/config.json
- Auto-approve: up to $0.10
- Log & approve: $0.10 - $1.00
- Requires click approval: $1.00 - $10.00
- Requires amount typing: $10.00 - $100.00
- Maximum per payment: $500.00
- Maximum per session: $100.00

Session:
- Spent: $0.45 (4,500 sats)
- Remaining: $99.55

Note: AI cannot modify budget limits. Edit config.json to change.

---

Invoice Tools (Strike, OpenNode)

create_invoice

Create a Lightning invoice to receive payments. Returns a BOLT11 string to share with the payer.

Parameters:

Parameter	Type	Required	Default	Description
amountSats	long	Yes	-	Amount to receive in satoshis
memo	string	No	null	Description for the invoice
expirySecs	int	No	3600	Invoice expiry (default 1 hour)

Example:

User: Create an invoice for 1000 sats for "Coffee payment"

Claude: [Uses create_invoice]

Invoice Created!
- Amount: 1,000 sats
- Memo: Coffee payment
- Expires: 1 hour
- Invoice ID: inv_abc123...

BOLT11 Invoice (share with payer):
lnbc10u1p3xyza...

Share this invoice with the payer, or display as a QR code.

Response:

{
  "success": true,
  "provider": "OpenNode",
  "invoice": {
    "id": "inv_abc123",
    "bolt11": "lnbc10u1p3xyza...",
    "amountSats": 1000,
    "expiresAt": "2024-01-15T14:30:00Z"
  },
  "message": "Invoice created for 1000 sats. Share the bolt11 string with the payer."
}

---

check_invoice_status

Check if a previously created invoice has been paid.

Parameters:

Parameter	Type	Required	Description
invoiceId	string	Yes	Invoice ID from create_invoice

Example:

User: Has the coffee invoice been paid?

Claude: [Uses check_invoice_status with invoiceId="inv_abc123"]

Invoice Status: PAID! ✅
- Amount: 1,000 sats
- Paid at: 2024-01-15 13:45:22 UTC

Response:

{
  "success": true,
  "provider": "OpenNode",
  "invoice": {
    "id": "inv_abc123",
    "state": "paid",
    "isPaid": true,
    "isPending": false,
    "amountSats": 1000,
    "paidAt": "2024-01-15T13:45:22Z"
  },
  "message": "Invoice inv_abc123 has been PAID!"
}

---

Strike-Only Tools

These tools are only available when using Strike as your wallet provider.

get_btc_price

Get the current Bitcoin price in USD.

Parameters: None required

Example:

User: What's the current Bitcoin price?

Claude: [Uses get_btc_price]

Current BTC Price: $97,500.00 USD
Source: Strike
Timestamp: 2024-01-15 13:30:00 UTC

Response:

{
  "success": true,
  "provider": "Strike",
  "ticker": {
    "btcUsd": 97500.00,
    "timestamp": "2024-01-15T13:30:00Z"
  },
  "message": "Current BTC price: $97,500.00 USD"
}

---

get_all_balances

Get all currency balances (USD and BTC) from your Strike wallet.

Parameters: None required

Example:

User: Show all my Strike balances

Claude: [Uses get_all_balances]

Strike Balances:
- USD: $127.45 (available)
- BTC: 0.00045000 BTC (45,000 sats, ~$45)

Total Value: ~$172.45 USD

Response:

{
  "success": true,
  "provider": "Strike",
  "balances": [
    {
      "currency": "USD",
      "available": 127.45,
      "total": 127.45,
      "pending": 0,
      "formatted": "127.45 USD"
    },
    {
      "currency": "BTC",
      "available": 0.00045000,
      "total": 0.00045000,
      "pending": 0,
      "formatted": "0.00045000 BTC (45,000 sats)"
    }
  ],
  "message": "Retrieved 2 currency balance(s) from Strike"
}

---

exchange_currency

Convert between USD and BTC within your Strike wallet.

Parameters:

Parameter	Type	Required	Description
sourceCurrency	string	Yes	Currency to convert from: USD or BTC
targetCurrency	string	Yes	Currency to convert to: BTC or USD
amount	decimal	Yes	Amount in source currency

Example - Buy Bitcoin:

User: Convert $50 to Bitcoin

Claude: [Uses exchange_currency with sourceCurrency=USD, targetCurrency=BTC, amount=50]

Exchange Complete!
- Converted: $50.00 USD
- Received: 0.00051282 BTC (51,282 sats)
- Rate: $97,500/BTC
- Fee: $0.25

Example - Sell Bitcoin:

User: Sell 0.001 BTC for dollars

Claude: [Uses exchange_currency with sourceCurrency=BTC, targetCurrency=USD, amount=0.001]

Exchange Complete!
- Converted: 0.001 BTC (100,000 sats)
- Received: $97.00 USD
- Rate: $97,500/BTC
- Fee: $0.50

---

send_onchain

Send an on-chain Bitcoin payment to a Bitcoin address (not Lightning).

Parameters:

Parameter	Type	Required	Description
address	string	Yes	Bitcoin address (bc1q..., 3..., or 1...)
amountSats	long	Yes	Amount to send in satoshis

Example:

User: Send 50000 sats to bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh

Claude: [Uses send_onchain]

On-Chain Payment Sent!
- Amount: 50,000 sats (0.0005 BTC)
- Address: bc1qxy2kg...
- Network Fee: 500 sats
- Status: COMPLETED
- Transaction ID: abc123def456...

On-Chain vs Lightning

On-chain payments are slower (10+ minutes) and have higher fees than Lightning. Use Lightning (pay_invoice) when possible.

---

L402 Tools (One-Time License)

These tools require a one-time L402 license purchase (6,000 sats, ~$6). Pay once, use forever!

How to Unlock L402 Features

Run the unlock_l402_features tool in Claude:

User: Unlock L402 features

Claude: [Uses unlock_l402_features]

L402 features unlocked!
- Amount paid: 6,000 sats (~$6)
- License bound to: your-wallet-pubkey...
- Valid: Forever

You can now use access_l402_resource and pay_l402_challenge tools.

The license is bound to your NWC wallet pubkey and stored locally at ~/.lightning-enable/license.json.

L402-Compatible Wallets Required

L402 requires a wallet that returns payment preimage. Use NWC with Alby, CoinOS, Mutiny, Zeus, or Bluewallet. Strike and Primal don't work for L402.

access_l402_resource

Fetch a URL with automatic L402 payment handling. When the API returns 402 Payment Required, the MCP automatically pays the invoice and retries with the L402 credential.

Parameters:

Parameter	Type	Required	Default	Description
url	string	Yes	-	URL to fetch
method	string	No	GET	HTTP method
headers	string	No	null	JSON object of headers
body	string	No	null	Request body
maxSats	int	No	1000	Maximum payment allowed

Example:

User: Fetch premium data from https://api.example.com/l402/data

Claude: [Uses access_l402_resource]

The API required a 50 sat payment which was automatically paid.

Response:
{
  "premium": "data...",
  "analysis": "..."
}

Payment Details:
- Amount: 50 sats ($0.05)
- L402 token cached for future requests

---

pay_l402_challenge

Manually pay an L402 invoice when you have the macaroon and invoice components separately.

Parameters:

Parameter	Type	Required	Default	Description
invoice	string	Yes	-	BOLT11 Lightning invoice
macaroon	string	Yes	-	Base64-encoded macaroon
maxSats	int	No	1000	Maximum payment allowed

Returns: L402 credential in format macaroon:preimage

---

Wallet Configuration

Strike (Recommended for USD Users)

Best for users who want USD balance management, BTC price tracking, and easy on/off ramps.

{
  "mcpServers": {
    "lightning-enable": {
      "command": "dotnet",
      "args": ["tool", "run", "lightning-enable-mcp"],
      "env": {
        "STRIKE_API_KEY": "your-strike-api-key"
      }
    }
  }
}

Setup:

1. Create account at https://strike.me
2. Get API key from https://dashboard.strike.me
3. Fund your account

Available Tools: All except L402 (no preimage)

---

NWC - Alby or CoinOS (Best for L402)

Best for L402 auto-pay. NWC wallets return preimage which is required for L402.

{
  "mcpServers": {
    "lightning-enable": {
      "command": "dotnet",
      "args": ["tool", "run", "lightning-enable-mcp"],
      "env": {
        "NWC_CONNECTION_STRING": "nostr+walletconnect://..."
      }
    }
  }
}

Setup:

1. Create wallet at https://coinos.io (free) or deploy Alby Hub
2. Go to Settings → NWC → Create connection
3. Enable auto-pay for the connection
4. Copy connection string
5. Run unlock_l402_features in Claude (one-time 6,000 sats)

Available Tools: All tools including L402

---

NWC (Nostr Wallet Connect)

Best for self-custody wallets. L402 support depends on wallet.

{
  "mcpServers": {
    "lightning-enable": {
      "command": "dotnet",
      "args": ["tool", "run", "lightning-enable-mcp"],
      "env": {
        "NWC_CONNECTION_STRING": "nostr+walletconnect://pubkey?relay=wss://relay.example.com&secret=xxx"
      }
    }
  }
}

Setup:

1. Use a compatible wallet (CoinOS, Alby Hub, or Primal)
2. Create NWC connection in wallet settings
3. Copy connection string

L402 Compatibility:

Wallet	L402 Works	Cost
CoinOS	✅ Yes	Free
Alby Hub	✅ Yes	Self-host or paid cloud
Primal	❌ No	Free

CoinOS for Free L402

CoinOS is completely free and returns preimages, so L402 works! Primal doesn't return preimages yet.

---

Budget Configuration

Spending limits are configured in ~/.lightning-enable/config.json (created automatically on first run):

{
  "currency": "USD",
  "tiers": {
    "autoApprove": 0.10,
    "logAndApprove": 1.00,
    "formConfirm": 10.00,
    "urlConfirm": 100.00
  },
  "limits": {
    "maxPerPayment": 500.00,
    "maxPerSession": 100.00
  },
  "session": {
    "cooldownSeconds": 1,
    "requireApprovalForFirstPayment": true
  }
}

Approval Tiers

Amount (USD)	Behavior
≤ $0.10	Auto-approved silently
$0.10 - $1.00	Approved but logged
$1.00 - $10.00	Click "Approve" in chat
$10.00 - $100.00	Type exact amount to confirm
> $500.00	Blocked entirely

Why This is AI-Proof

• Config file lives in your home directory, not environment variables
• No MCP tool can modify budget limits
• Only you can edit the config file
• Large payments require human verification (typing amount)

---

Environment Variables Reference

Variable	Required	Default	Description
STRIKE_API_KEY	If using Strike	-	Strike API key
OPENNODE_API_KEY	If using OpenNode	-	OpenNode API key
OPENNODE_ENVIRONMENT	No	production	production or dev
NWC_CONNECTION_STRING	If using NWC	-	Nostr Wallet Connect URI
LND_REST_HOST	If using LND	-	LND REST API host
LND_MACAROON_HEX	If using LND	-	LND admin macaroon in hex
LIGHTNING_ENABLE_API_URL	No	https://api.lightningenable.com	API base URL

L402 License

L402 features don't require an API key. Just run unlock_l402_features to purchase a license with Lightning (6,000 sats, one-time).

---

Security Best Practices

1. Use a dedicated wallet - Never use your main wallet or business funds for AI spending
2. Configure budget limits - Edit ~/.lightning-enable/config.json before first use
3. Review payment history - Check get_payment_history after sessions
4. Rotate API keys - Monthly rotation recommended
5. Never commit keys - Keep API keys out of version control

See AI Spending Security for detailed security guidance.

---

Troubleshooting

"Wallet not configured"

Set one of: STRIKE_API_KEY, OPENNODE_API_KEY, or NWC_CONNECTION_STRING

"Budget limit exceeded"

Payment exceeds your limits. Use get_budget_status to see current limits, edit config file to adjust.

"License required for L402 features"

L402 tools require a one-time license. Use the unlock_l402_features tool to purchase for 6,000 sats (~$6). Valid forever.

"Feature not supported"

Some features are wallet-specific (e.g., BTC price is Strike-only). Check the compatibility table above.

"L402 payment succeeded but access failed"

Your wallet doesn't return preimage. Use OpenNode, Alby, or CoinOS. Primal doesn't work for L402 yet.

---

Next Steps

• MCP Wallet Setup - Detailed wallet configuration
• AI Spending Security - Budget configuration
• AI Agent Integration - Advanced usage