Lightning MCP Server

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).

Security Scan

The skill's files, scripts, and runtime instructions are internally consistent with its stated purpose of building/configuring an MCP LNC server and registering it with Claude Code, but there are a few operational risks you should review before installing (external package downloads, Docker image source, and config writes).

Purpose & Capability

The name/description match the provided SKILL.md and scripts: scripts build a local binary (Go), create a .env, and add an MCP server entry to Claude Code config (.mcp.json or ~/.claude.json). Required tools (go, jq) and env keys referenced in the docs align with the stated function; no unrelated credentials or binaries are requested.

Instruction Scope

Runtime instructions are narrowly scoped to building the server, writing a lightning-mcp-server/.env, and adding an entry to Claude Code's MCP configuration. The scripts read only the .env they create (and only known variables), and they write project/global MCP config files as expected for registration. They do not attempt to read arbitrary system files or exfiltrate unrelated data.

Install Mechanism

There is no centralized install spec in the registry entry, but the SKILL.md offers multiple installation paths: (a) build-from-source via included install.sh (requires Go and local source — low risk), (b) zero-install 'npx -y @lightninglabs/lightning-mcp-server' which downloads/executes code from the npm registry (moderate risk unless you verify the package), and (c) running an unspecified Docker image name 'lightning-mcp-server' (moderate/high risk depending on image source). Review the npm package and Docker image origin before using those paths.

Credentials

The skill declares no required credentials or config paths in the registry metadata. The scripts create and read a controlled .env in the lightning-mcp-server directory (LNC_MAILBOX_SERVER, LNC_DEV_MODE, LNC_INSECURE, LNC_CONNECT_TIMEOUT) which are appropriate for LNC operation. There are no requests for unrelated secrets or cloud credentials.

Persistence & Privilege

The skill does modify Claude Code configuration files (.mcp.json in the project or ~/.claude.json for global scope) to register itself as an MCP server — this is expected for integration, but it is a change to agent config outside the skill's own directory. always:false and no autonomous privilege escalation flagged.

Assessment

This skill appears to do what it says: build/configure an MCP LNC server and register it with Claude Code. Before installing, consider the following: 1) The SKILL.md suggests using 'npx @lightninglabs/lightning-mcp-server' — that will download and run code from npm. Verify the npm package name, its publisher, and its source repository before running. 2) The Docker option references an image name but not a registry or explicit tag; prefer explicit, trusted images (and inspect Dockerfile/source) before pulling. 3) Running setup-claude-config.sh can write to your project .mcp.json or your global ~/.claude.json — review the resulting file before restarting Claude Code. 4) The pairing phrase used to connect to lnd is sensitive; ensure you only provide it to trusted code and environments. 5) Use LNC_INSECURE only for local dev/regtest; do not disable TLS verification in production. If you want higher assurance, request the upstream source repository or a signed release, and inspect the npm package and Docker image referenced in the docs.

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

1. Claude Code launches lightning-mcp-server as a subprocess (stdio transport)
2. Agent calls lnc_connect with a pairing phrase and password
3. Server generates an ephemeral ECDSA keypair and opens an encrypted WebSocket tunnel through the mailbox relay
4. Once connected, the agent can call any of the 18 read-only tools
5. 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.

Option 3: Manual configuration

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"
      ]
    }
  }
}

Available Tools (18)

Connection

Tool	Description
lnc_connect	Connect to lnd via LNC pairing phrase
lnc_disconnect	Close active LNC connection

Node

Tool	Description
lnc_get_info	Node alias, version, sync status, block height
lnc_get_balance	Wallet balance (on-chain) and channel balance

Channels

Tool	Description
lnc_list_channels	Active/inactive channels with capacity, balances
lnc_pending_channels	Channels being opened or closed

Invoices

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

Payments

Tool	Description
lnc_list_payments	Payment history with pagination
lnc_track_payment	Track specific payment by hash

Peers & Network

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

On-Chain

Tool	Description
lnc_list_unspent	UTXOs with confirmations
lnc_get_transactions	On-chain transaction history
lnc_estimate_fee	Fee estimates for confirmation targets

Security Model

• No stored credentials: Pairing phrase is handled in-memory only. Ephemeral ECDSA keypairs are generated per session.
• Read-only: No payment, channel, or state-changing operations are exposed. The agent can observe but not modify.
• Encrypted tunnels: All traffic is encrypted end-to-end through the mailbox relay. The mailbox cannot read the traffic.
• No direct access: The agent machine never connects directly to the lnd node's gRPC port — all traffic goes through the mailbox.

Comparison with Direct gRPC Access

	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

Prerequisites

• Go 1.24+ for building from source
• Lightning Terminal (litd) on the target node for generating pairing phrases
• Claude Code for MCP integration

Troubleshooting

"pairing phrase must be exactly 10 words"

The pairing phrase is generated by Lightning Terminal. It must be exactly 10 space-separated words.

"connection timeout"

Check that the mailbox server is reachable. For production, ensure mailbox.terminal.lightning.today:443 is not blocked by a firewall.

"TLS handshake failure"

If using a local regtest setup, enable dev mode and insecure mode:

skills/lightning-mcp-server/scripts/configure.sh --dev --insecure

Tools not appearing in Claude Code

Restart Claude Code after running setup-claude-config.sh. Check that lightning-mcp-server is on your $PATH:

which lightning-mcp-server