Builds Go-based MCP server for read-only queries of Lightning Network lnd nodes via secure LNC WebSocket tunnels using pairing phrases. Includes 18 tools for state, channels, payments.
npx claudepluginhub lightninglabs/lightning-agent-tools --plugin lightning-agent-toolsThis skill uses the workspace's default tool permissions.
Build and configure the MCP server that connects AI assistants to Lightning
Installs and runs Lightning Terminal (litd) in Docker bundling lnd, loop, pool, tapd, faraday for Lightning nodes. Handles payments, liquidity, channels, taproot assets on testnet/mainnet/regtest.
Guides MCP server integration in Claude Code plugins via .mcp.json or plugin.json configs for stdio, SSE, HTTP types, enabling external services as tools.
Configures MCP servers in Claude Code plugins via .mcp.json or plugin.json, supports stdio/SSE/HTTP/WebSocket, env vars, tool naming, OAuth/token auth, security, and testing.
Share bugs, ideas, or general feedback.
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.
# 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.
Claude Code <--stdio--> lightning-mcp-server <--LNC WebSocket--> Mailbox <--> lnd
lightning-mcp-server as a subprocess (stdio transport)lnc_connect with a pairing phrase and passwordlnc_disconnect closes the tunnelNo keys, certs, or macaroons are stored on disk — the pairing phrase is the only credential, and it's handled in-memory only.
# 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.
# 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 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).
# 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.
Add to .mcp.json in your project root:
{
"mcpServers": {
"lnc": {
"command": "npx",
"args": ["-y", "@lightninglabs/lightning-mcp-server"],
"env": {
"LNC_MAILBOX_SERVER": "mailbox.terminal.lightning.today:443"
}
}
}
}
Or with a locally built binary:
{
"mcpServers": {
"lnc": {
"command": "lightning-mcp-server",
"env": {
"LNC_MAILBOX_SERVER": "mailbox.terminal.lightning.today:443"
}
}
}
}
Or run via Docker:
{
"mcpServers": {
"lnc": {
"command": "docker",
"args": [
"run", "--rm", "-i", "--network", "host",
"--env", "LNC_MAILBOX_SERVER",
"--env", "LNC_DEV_MODE",
"--env", "LNC_INSECURE",
"lightning-mcp-server"
]
}
}
}
| Tool | Description |
|---|---|
lnc_connect | Connect to lnd via LNC pairing phrase |
lnc_disconnect | Close active LNC connection |
| Tool | Description |
|---|---|
lnc_get_info | Node alias, version, sync status, block height |
lnc_get_balance | Wallet balance (on-chain) and channel balance |
| Tool | Description |
|---|---|
lnc_list_channels | Active/inactive channels with capacity, balances |
lnc_pending_channels | Channels being opened or closed |
| Tool | Description |
|---|---|
lnc_decode_invoice | Decode a BOLT11 invoice |
lnc_list_invoices | List invoices with pagination |
lnc_lookup_invoice | Look up invoice by payment hash |
| Tool | Description |
|---|---|
lnc_list_payments | Payment history with pagination |
lnc_track_payment | Track specific payment by hash |
| Tool | Description |
|---|---|
lnc_list_peers | Connected peers with stats |
lnc_describe_graph | Lightning Network topology sample |
lnc_get_node_info | Detailed info about a specific node |
| Tool | Description |
|---|---|
lnc_list_unspent | UTXOs with confirmations |
lnc_get_transactions | On-chain transaction history |
lnc_estimate_fee | Fee estimates for confirmation targets |
| MCP LNC Server | Direct lncli/gRPC | |
|---|---|---|
| Credential | Pairing phrase (in-memory) | TLS cert + macaroon (on disk) |
| Network | WebSocket via mailbox relay | Direct TCP to gRPC port |
| Firewall | No inbound ports needed | Port 10009 must be reachable |
| Permissions | Read-only (hardcoded) | Depends on macaroon scope |
| Setup | Pairing phrase from Lightning Terminal | Export cert + macaroon files |
The pairing phrase is generated by Lightning Terminal. It must be exactly 10 space-separated words.
Check that the mailbox server is reachable. For production, ensure
mailbox.terminal.lightning.today:443 is not blocked by a firewall.
If using a local regtest setup, enable dev mode and insecure mode:
skills/lightning-mcp-server/scripts/configure.sh --dev --insecure
Restart Claude Code after running setup-claude-config.sh. Check that
lightning-mcp-server is on your $PATH:
which lightning-mcp-server