# Send Lightning MCP Server to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "lightning-mcp-server",
    "name": "Lightning MCP Server",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/Roasbeef/lightning-mcp-server",
    "canonicalUrl": "https://clawhub.ai/Roasbeef/lightning-mcp-server",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/lightning-mcp-server",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=lightning-mcp-server",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "SKILL.md",
      "templates/env.txt",
      "scripts/install.sh",
      "scripts/setup-claude-config.sh",
      "scripts/configure.sh"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "lightning-mcp-server",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-04T23:30:53.207Z",
      "expiresAt": "2026-05-11T23:30:53.207Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=lightning-mcp-server",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=lightning-mcp-server",
        "contentDisposition": "attachment; filename=\"lightning-mcp-server-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "lightning-mcp-server"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/lightning-mcp-server"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/lightning-mcp-server",
    "downloadUrl": "https://openagent3.xyz/downloads/lightning-mcp-server",
    "agentUrl": "https://openagent3.xyz/skills/lightning-mcp-server/agent",
    "manifestUrl": "https://openagent3.xyz/skills/lightning-mcp-server/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/lightning-mcp-server/agent.md"
  }
}
```
## Documentation

### 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:

VariableDefaultDescriptionLNC_MAILBOX_SERVERmailbox.terminal.lightning.today:443Mailbox relay serverLNC_DEV_MODEfalseEnable development modeLNC_INSECUREfalseSkip TLS verification (dev only)LNC_CONNECT_TIMEOUT30Connection timeout in seconds

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

### Connection

ToolDescriptionlnc_connectConnect to lnd via LNC pairing phraselnc_disconnectClose active LNC connection

### Node

ToolDescriptionlnc_get_infoNode alias, version, sync status, block heightlnc_get_balanceWallet balance (on-chain) and channel balance

### Channels

ToolDescriptionlnc_list_channelsActive/inactive channels with capacity, balanceslnc_pending_channelsChannels being opened or closed

### Invoices

ToolDescriptionlnc_decode_invoiceDecode a BOLT11 invoicelnc_list_invoicesList invoices with paginationlnc_lookup_invoiceLook up invoice by payment hash

### Payments

ToolDescriptionlnc_list_paymentsPayment history with paginationlnc_track_paymentTrack specific payment by hash

### Peers & Network

ToolDescriptionlnc_list_peersConnected peers with statslnc_describe_graphLightning Network topology samplelnc_get_node_infoDetailed info about a specific node

### On-Chain

ToolDescriptionlnc_list_unspentUTXOs with confirmationslnc_get_transactionsOn-chain transaction historylnc_estimate_feeFee 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 ServerDirect lncli/gRPCCredentialPairing phrase (in-memory)TLS cert + macaroon (on disk)NetworkWebSocket via mailbox relayDirect TCP to gRPC portFirewallNo inbound ports neededPort 10009 must be reachablePermissionsRead-only (hardcoded)Depends on macaroon scopeSetupPairing phrase from Lightning TerminalExport 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

### "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
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: Roasbeef
- Version: 1.0.0
## Source health
- Status: healthy
- Item download looks usable.
- Yavira can redirect you to the upstream package for this item.
- Health scope: item
- Reason: direct_download_ok
- Checked at: 2026-05-04T23:30:53.207Z
- Expires at: 2026-05-11T23:30:53.207Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/lightning-mcp-server)
- [Send to Agent page](https://openagent3.xyz/skills/lightning-mcp-server/agent)
- [JSON manifest](https://openagent3.xyz/skills/lightning-mcp-server/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/lightning-mcp-server/agent.md)
- [Download page](https://openagent3.xyz/downloads/lightning-mcp-server)