Skip to main content

Lightning MCP: 5-Minute Setup

Get your AI paying Lightning invoices in under 5 minutes. No credit card, no subscription - just Bitcoin.

What You'll Get

After this guide, Claude can:

  • Pay any Lightning invoice you give it
  • Check your wallet balance
  • View payment history
  • All for free - no subscription required

What You Need​

  1. Claude Code (Claude's CLI) - Already installed
  2. A Lightning wallet that supports NWC - We'll set one up

That's it. Let's go.

Step 1: Create a Free CoinOS Wallet (2 minutes)​

CoinOS is a free Lightning wallet that works perfectly with Claude.

  1. Go to https://coinos.io
  2. Click "Get Started" - no email required
  3. Write down your password (you'll need it later)
  4. Done! You have a Lightning wallet.

Fund Your Wallet​

Send a small amount of Bitcoin to your CoinOS wallet:

  • Click Receive in CoinOS
  • Copy the Lightning address or invoice
  • Send from any other wallet (start with $1-5 worth)
No Bitcoin?

You can buy directly in CoinOS, or use an exchange like Strike, Cash App, or River.

Step 2: Create NWC Connection (1 minute)​

NWC (Nostr Wallet Connect) lets Claude pay invoices from your wallet.

  1. In CoinOS, go to Settings (gear icon)
  2. Click Nostr Wallet Connect
  3. Click Add a new connection
  4. Name it "Claude Code"
  5. Enable auto-pay (toggle ON)
  6. Set budget limit (e.g., 10,000 sats per day)
  7. Click Create
  8. Copy the connection string (starts with nostr+walletconnect://)

Save this string - you'll need it in the next step.

Step 3: Configure Claude (2 minutes)​

Add the Lightning Enable MCP server to Claude's configuration.

Edit your Claude config file:

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

Add this to your mcpServers section:

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

Replace YOUR_STRING_HERE with your CoinOS connection string.

Option B: Config File (For Special Characters)​

If your connection string has characters that don't work in JSON, use a config file instead.

Create ~/.lightning-enable/config.json:

{
  "wallets": {
    "nwcConnectionString": "nostr+walletconnect://YOUR_STRING_HERE"
  }
}

Then use this simpler MCP config:

{
  "mcpServers": {
    "lightning-enable": {
      "command": "dotnet",
      "args": ["tool", "run", "lightning-enable-mcp"]
    }
  }
}

Step 4: Install the MCP Server (30 seconds)​

Open your terminal and run:

dotnet tool install --global lightning-enable-mcp

That's it. Restart Claude.

Step 5: Test It! (30 seconds)​

Open Claude and try these:

Check Your Balance​

Check my Lightning balance

Claude will show your CoinOS balance.

Pay an Invoice​

Pay this Lightning invoice: lnbc...

Give Claude any BOLT11 invoice and it will pay it from your wallet.

View Payment History​

Show my recent Lightning payments

You're Done!​

Claude can now make Lightning payments for you. Here's what's available for free:

ToolWhat It Does
pay_invoicePay any Lightning invoice
check_wallet_balanceSee your wallet balance
get_payment_historyView recent payments
get_budget_statusCheck spending limits
create_invoiceCreate invoices to receive payments
check_invoice_statusCheck if someone paid your invoice

Real-World Examples​

Tip a Content Creator​

Pay this Lightning tip: lnbc210n1pj...

Buy API Access​

I need to pay for this API. Here's the invoice: lnbc50u1pj...

Split a Bill​

Pay my share of the bill: lnbc15000n1pj...

Receive Payments​

Create a Lightning invoice for 5000 sats with memo "Thanks!"

Set Spending Limits​

Protect yourself with spending limits. Create ~/.lightning-enable/config.json:

{
  "currency": "USD",
  "tiers": {
    "autoApprove": 0.10,
    "logAndApprove": 1.00,
    "formConfirm": 10.00
  },
  "limits": {
    "maxPerPayment": 50.00,
    "maxPerSession": 20.00
  }
}

This means:

  • Under $0.10: Auto-pay, no questions
  • $0.10-$1.00: Pay but log it
  • $1.00-$10.00: Ask for confirmation
  • Over $50 per payment: Denied
  • Over $20 per session: Denied

Want L402 Auto-Pay?​

The free tier handles direct invoice payments. For automatic L402 API payments (like AI agents that pay for API access automatically), unlock L402 features with a one-time Lightning payment.

Unlock L402 Features (One-Time 6,000 sats)​

Just ask Claude to unlock L402:

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

L402 unlocks these tools:

  • access_l402_resource - Automatically pay L402 challenges
  • pay_l402_challenge - Manual L402 payment handling
Already Bought a License?

Your license is bound to your wallet pubkey. If you switch devices, just run unlock_l402_features again - it will restore your existing license without charging you.

Troubleshooting​

"Wallet not configured"​

Your NWC connection string isn't being read. Check:

  1. Environment variable is set correctly
  2. Or config file exists at ~/.lightning-enable/config.json
  3. Connection string starts with nostr+walletconnect://

"Payment cancelled by user"​

Auto-pay isn't enabled in CoinOS. Go to Settings > NWC > Edit your connection > Toggle auto-pay ON.

"dotnet: command not found"​

Install .NET 8 SDK from https://dot.net/download

Payments are slow​

CoinOS uses Lightning routing which can take a few seconds. This is normal.

Next Steps​

Quick Reference​

SettingWhere
NWC ConnectionCoinOS Settings > Nostr Wallet Connect
Claude Config~/Library/Application Support/Claude/claude_desktop_config.json (Mac)
Budget Config~/.lightning-enable/config.json
MCP Installdotnet tool install --global lightning-enable-mcp

Questions? Check the FAQ or open an issue on GitHub.