Build and configure the MCP server for Lightning Node Connect (LNC). Connects AI assistants to lnd nodes via encrypted WebSocket tunnels using pairing phrases — no direct network access or TLS certs needed. Read-only by default (18 tools for querying node state, channels, payments, invoices, peers, on-chain data).
Build and configure the MCP server for Lightning Node Connect (LNC). Connects AI assistants to lnd nodes via encrypted WebSocket tunnels using pairing phrases — no direct network access or TLS certs needed. Read-only by default (18 tools for querying node state, channels, payments, invoices, peers, on-chain data).
MCP LNC Server
Build and configure the MCP server that connects AI assistants to Lightning
nodes via Lightning Node Connect (LNC). LNC uses encrypted WebSocket tunnels
through a mailbox relay, so the agent never needs direct gRPC access, TLS
certificates, or macaroons — just a 10-word pairing phrase from Lightning
Terminal.
The MCP server is read-only by default — it exposes 18 tools for querying
node state but cannot send payments or modify channels.
Quick Start
# 1. Build the MCP server binary
skills/lightning-mcp-server/scripts/install.sh
# 2. Configure environment (mailbox server, dev mode, etc.)
skills/lightning-mcp-server/scripts/configure.sh
# 3. Add to Claude Code as an MCP server
skills/lightning-mcp-server/scripts/setup-claude-config.sh
Then restart Claude Code. The lnc_connect tool will be available to connect
to any lnd node using a pairing phrase.
How It Works
Claude Code <--stdio--> lightning-mcp-server <--LNC WebSocket--> Mailbox <--> lnd
Claude Code launches lightning-mcp-server as a subprocess (stdio transport)
Agent calls lnc_connect with a pairing phrase and password
Server generates an ephemeral ECDSA keypair and opens an encrypted WebSocket
tunnel through the mailbox relay
Once connected, the agent can call any of the 18 read-only tools
lnc_disconnect closes the tunnel
No keys, certs, or macaroons are stored on disk — the pairing phrase is the
only credential, and it's handled in-memory only.
Installation
# Build from source (requires Go 1.24+)
skills/lightning-mcp-server/scripts/install.sh
# Verify
lightning-mcp-server -version
The install script builds from the lightning-mcp-server/ directory in this repo.
Configuration
# Generate .env with defaults
skills/lightning-mcp-server/scripts/configure.sh
# Production (mainnet via Lightning Terminal)
skills/lightning-mcp-server/scripts/configure.sh --production
# Development (local regtest)
skills/lightning-mcp-server/scripts/configure.sh --dev --mailbox aperture:11110
Configuration is stored in lightning-mcp-server/.env. Key settings:
Variable
Default
Description
LNC_MAILBOX_SERVER
mailbox.terminal.lightning.today:443
Mailbox relay server
LNC_DEV_MODE
false
Enable development mode
LNC_INSECURE
false
Skip TLS verification (dev only)
LNC_CONNECT_TIMEOUT
30
Connection timeout in seconds
Claude Code Integration
Option 1: claude mcp add (recommended)
Register the MCP server with a single command — no build step required:
# Zero-install via npx (downloads pre-built binary)
claude mcp add --transport stdio lnc -- npx -y @lightninglabs/lightning-mcp-server
# With environment variables for production
claude mcp add --transport stdio \
--env LNC_MAILBOX_SERVER=mailbox.terminal.lightning.today:443 \
lnc -- npx -y @lightninglabs/lightning-mcp-server
# For development/regtest
claude mcp add --transport stdio \
--env LNC_MAILBOX_SERVER=localhost:11110 \
--env LNC_DEV_MODE=true \
--env LNC_INSECURE=true \
lnc -- npx -y @lightninglabs/lightning-mcp-server
Scope options: --scope local (default, just you), --scope project (shared
via .mcp.json), --scope user (all your projects).
Option 2: Setup script (from source)
# Add lightning-mcp-server to Claude Code's MCP config
skills/lightning-mcp-server/scripts/setup-claude-config.sh
# Project-level config (current project only)
skills/lightning-mcp-server/scripts/setup-claude-config.sh --scope project
# Global config (all projects)
skills/lightning-mcp-server/scripts/setup-claude-config.sh --scope global
This adds the server to Claude Code's .mcp.json (project) or
~/.claude.json (global) configuration. After restarting Claude Code, the
LNC tools will be available.
