LND Node Setup Guide

This guide covers connecting the Lightning Enable MCP server to your own LND (Lightning Network Daemon) node. LND always returns the preimage, making it the most reliable option for L402 authentication.

Why Use Your Own LND Node?

Benefit	Description
Guaranteed L402	LND always returns preimage - L402 never fails due to wallet limitations
Self-Custody	You control your funds, not a third party
No API Limits	No rate limits or account restrictions
No Custody Risk	No third-party custody = no counterparty risk
No Regulatory Risk	Not using a money transmitter for payments

Best For

LND is ideal for:

Power users who already run Lightning nodes
Businesses that need 100% L402 reliability
Users who want full self-custody
Developers testing L402 implementations

Prerequisites

You Need

A running LND node with:
- REST API enabled (default port 8080)
- Funded channels with outbound liquidity
- Admin macaroon access
Network access from your MCP server to LND:
- Same machine: localhost:8080
- Local network: 192.168.x.x:8080
- Remote: VPN or Tor recommended

LND Installation Options

If you don't have LND yet:

Platform	Recommended Approach
Start9	Built-in LND package
Umbrel	Lightning app from store
RaspiBlitz	Included by default
Voltage	Cloud-hosted LND
Manual	LND Installation Guide

Step 1: Enable LND REST API

LND's REST API is enabled by default on port 8080. Verify in your lnd.conf:

[Application Options]
# REST API (enabled by default)
restlisten=0.0.0.0:8080

# TLS settings
tlsextraip=0.0.0.0
tlsextradomain=your-domain.com

If you changed the port, note it for configuration.

Restart LND After Config Changes

# Stop LND
lncli stop

# Start LND (method depends on your setup)
lnd
# or
systemctl restart lnd

Step 2: Get Your Admin Macaroon

The macaroon is your authentication credential. You need the admin macaroon for payments.

Location by Platform

Platform	Default Path
Linux	`~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon`
macOS	`~/Library/Application Support/Lnd/data/chain/bitcoin/mainnet/admin.macaroon`
Windows	`%LOCALAPPDATA%\Lnd\data\chain\bitcoin\mainnet\admin.macaroon`
Start9	SSH in, check `/embassy-data/package-data/volumes/lnd/`
Umbrel	`~/umbrel/app-data/lightning/data/lnd/data/chain/bitcoin/mainnet/admin.macaroon`
Docker	Inside container at `/root/.lnd/data/chain/bitcoin/mainnet/admin.macaroon`

Convert Macaroon to Hex

The MCP server needs the macaroon in hex format (not base64).

Linux/macOS:

xxd -ps -c 1000 ~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon

Windows PowerShell:

[System.BitConverter]::ToString([System.IO.File]::ReadAllBytes("$env:LOCALAPPDATA\Lnd\data\chain\bitcoin\mainnet\admin.macaroon")) -replace '-',''

Docker:

docker exec lnd xxd -ps -c 1000 /root/.lnd/data/chain/bitcoin/mainnet/admin.macaroon

The output looks like:

0201036c6e6402f801030a10b3b1a4d3e5f6789012345678901234561201...

Save this string - you'll need it for configuration.

Step 3: Test LND Connection

Before configuring the MCP server, verify LND is accessible:

# Test from the machine running MCP
curl --insecure \
  -H "Grpc-Metadata-macaroon: YOUR_MACAROON_HEX" \
  https://localhost:8080/v1/getinfo

You should see JSON output with your node info:

{
  "identity_pubkey": "03abc...",
  "alias": "MyNode",
  "num_active_channels": 5,
  ...
}

Common Test Issues

Error	Solution
`Connection refused`	LND not running or REST not enabled
`certificate unknown`	Use `--insecure` or configure TLS cert
`permission denied`	Wrong macaroon or insufficient permissions
`timeout`	Firewall blocking port 8080

Step 4: Configure MCP Server

Option A: Environment Variables

{
  "mcpServers": {
    "lightning-enable": {
      "command": "dotnet",
      "args": ["tool", "run", "lightning-enable-mcp"],
      "env": {
        "LND_REST_HOST": "localhost:8080",
        "LND_MACAROON_HEX": "0201036c6e6402f801030a10...",
        "LIGHTNING_ENABLE_API_KEY": "your-merchant-api-key"
      }
    }
  }
}

Option B: Config File (Recommended)

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

{
  "currency": "USD",
  "tiers": {
    "autoApprove": 0.10,
    "logAndApprove": 1.00,
    "formConfirm": 10.00,
    "urlConfirm": 100.00
  },
  "limits": {
    "maxPerPayment": 500.00,
    "maxPerSession": 100.00
  },
  "session": {
    "requireApprovalForFirstPayment": false,
    "cooldownSeconds": 2
  },
  "wallets": {
    "lndRestHost": "localhost:8080",
    "lndMacaroonHex": "0201036c6e6402f801030a10b3b1a4d3e5f6789012345678901234561201...",
    "priority": "lnd"
  }
}

Configuration Options

Variable	Config Key	Description	Required
`LND_REST_HOST`	`lndRestHost`	LND REST API endpoint	Yes
`LND_MACAROON_HEX`	`lndMacaroonHex`	Admin macaroon in hex	Yes
`WALLET_PRIORITY`	`priority`	Set to "lnd"	Optional

Step 5: Verify Connection

Restart Claude Code and check the MCP server logs:

[LND] Initialized REST client for localhost:8080
Using LND wallet backend
LND always returns preimage - L402 fully supported

Test with a balance check:

User: Check my Lightning balance

Claude: [Uses check_wallet_balance]
Your LND balance: 500,000 sats

Remote LND Access

Same Local Network

{
  "wallets": {
    "lndRestHost": "192.168.1.100:8080"
  }
}

Over Tor (Most Secure)

Get your LND Tor address from lnd.conf or:

cat ~/.lnd/data/tor/v3_onion_service_address

Configure MCP (requires Tor proxy):

{
  "wallets": {
    "lndRestHost": "abcdef123456.onion:8080"
  }
}

Over VPN

Connect both machines to same VPN

Use VPN IP address:

{
  "wallets": {
    "lndRestHost": "10.8.0.1:8080"
  }
}

TLS Certificate Handling

For remote connections, you may need to handle TLS:

Option 1: Skip TLS verification (development only) Set environment variable:

LND_SKIP_TLS_VERIFY=true

Option 2: Provide TLS cert (production) Copy ~/.lnd/tls.cert to MCP machine and set:

LND_TLS_CERT_PATH=/path/to/tls.cert

Available Tools with LND

Tool	Description	Works with LND
`pay_invoice`	Pay any Lightning invoice	✅ Yes (with preimage)
`check_wallet_balance`	View channel balance	✅ Yes
`create_invoice`	Create invoice to receive	✅ Yes
`check_invoice_status`	Check if invoice paid	✅ Yes
`send_onchain`	Send on-chain Bitcoin	✅ Yes
`access_l402_resource`	L402 auto-pay	✅ Yes
`pay_l402_challenge`	Manual L402 payment	✅ Yes
`get_all_balances`	Multi-currency balance	✅ Yes (BTC only)

Tools NOT Available with LND

get_btc_price - Use Strike for price data
exchange_currency - LND is BTC-only

Troubleshooting

"Failed to connect to LND"

Check LND is running:

lncli getinfo

Check REST port is open:

netstat -tlnp | grep 8080

Check firewall:

# Linux
sudo ufw status
# or
sudo iptables -L

# Allow port 8080
sudo ufw allow 8080

"Permission denied" or "Macaroon invalid"

Verify macaroon is correct:

# Re-export macaroon
xxd -ps -c 1000 ~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon

Check macaroon permissions:

# Bake a new admin macaroon if needed
lncli bakemacaroon --save_to=./admin.macaroon \
  uri:/lnrpc.Lightning/GetInfo \
  uri:/lnrpc.Lightning/ListChannels \
  uri:/lnrpc.Lightning/ChannelBalance \
  uri:/lnrpc.Lightning/SendPayment \
  uri:/invoicesrpc.Invoices/AddInvoice \
  uri:/routerrpc.Router/SendPaymentV2

"No route found" / "FAILURE_REASON_NO_ROUTE"

Your node can't find a path to the destination:

Check outbound liquidity:

lncli listchannels | jq '.channels[] | {alias: .peer_alias, local: .local_balance, remote: .remote_balance}'

Open new channels to well-connected nodes
Wait for channel confirmation if recently opened

"Invoice expired"

The L402 invoice expired before payment completed. This can happen with:

Slow network connections
Large payments requiring route finding

Try again - the API will issue a fresh invoice.

"TLS handshake failed"

For self-signed certs (development):

{
  "env": {
    "LND_SKIP_TLS_VERIFY": "true"
  }
}

For production: Copy your tls.cert to the MCP server location.

Security Best Practices

1. Use Read-Only Macaroon for Balance Checks

If you only need balance checking (not payments):

lncli bakemacaroon --save_to=./readonly.macaroon \
  uri:/lnrpc.Lightning/GetInfo \
  uri:/lnrpc.Lightning/ListChannels \
  uri:/lnrpc.Lightning/ChannelBalance

2. Limit Macaroon Scope

Create a macaroon with only payment permissions:

lncli bakemacaroon --save_to=./payment.macaroon \
  uri:/lnrpc.Lightning/SendPayment \
  uri:/routerrpc.Router/SendPaymentV2 \
  uri:/lnrpc.Lightning/ChannelBalance

3. Use Tor for Remote Access

Never expose LND REST API directly to the internet. Use Tor hidden service instead.

4. Set Payment Limits in Config

The MCP config file provides additional spending controls:

{
  "limits": {
    "maxPerPayment": 100.00,
    "maxPerSession": 50.00
  }
}

Performance Tips

Channel Management

For best L402 performance:

Maintain 5+ active channels
Keep channels balanced (50% local / 50% remote)
Open channels to well-connected LSPs (Lightning Service Providers)

Recommended LSPs for Connectivity

ACINQ (Phoenix)
Breez
Voltage
LND Labs

Monitoring

Use lncli to monitor your node:

# Check pending payments
lncli listpayments --max_payments 10

# Check channel health
lncli listchannels --active_only

# Check forwards (routing)
lncli fwdinghistory

Frequently Asked Questions

Can I use LND on a Raspberry Pi?

Yes, but ensure adequate resources:

4GB+ RAM
SSD storage (not SD card)
Stable internet connection

Does this work with Core Lightning (CLN)?

Not yet. LND is currently the only supported node implementation. CLN support may be added in the future.

Can I use a hosted LND (Voltage, etc.)?

Yes! Voltage and similar services provide the REST API and macaroon. Configure as remote connection.

What if my node is offline?

Payments will fail. Ensure your node has reliable uptime for production use.

Is my macaroon safe in the config file?

The config file is stored locally on your machine. Keep it protected like any credential file:

Don't commit to git
Use file permissions (chmod 600)
Consider encrypted storage

Next Steps

AI Agent Integration - Using L402 tools
AI Spending Security - Budget configuration
Wallet Configuration - Other wallet options

Why Use Your Own LND Node?​

Prerequisites​

You Need​

LND Installation Options​

Step 1: Enable LND REST API​

Restart LND After Config Changes​

Step 2: Get Your Admin Macaroon​

Location by Platform​

Convert Macaroon to Hex​

Step 3: Test LND Connection​

Common Test Issues​

Step 4: Configure MCP Server​

Option A: Environment Variables​

Option B: Config File (Recommended)​

Configuration Options​

Step 5: Verify Connection​

Remote LND Access​

Same Local Network​

Over Tor (Most Secure)​

Over VPN​

TLS Certificate Handling​

Available Tools with LND​

Tools NOT Available with LND​

Troubleshooting​

"Failed to connect to LND"​

"Permission denied" or "Macaroon invalid"​

"No route found" / "FAILURE_REASON_NO_ROUTE"​

"Invoice expired"​

"TLS handshake failed"​

Security Best Practices​

1. Use Read-Only Macaroon for Balance Checks​

2. Limit Macaroon Scope​

3. Use Tor for Remote Access​

4. Set Payment Limits in Config​

Performance Tips​

Channel Management​

Recommended LSPs for Connectivity​

Monitoring​

Frequently Asked Questions​

Can I use LND on a Raspberry Pi?​

Does this work with Core Lightning (CLN)?​

Can I use a hosted LND (Voltage, etc.)?​

What if my node is offline?​

Is my macaroon safe in the config file?​

Next Steps​