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
CODEBLOCK0
Then restart Claude Code. The lnc_connect tool will be available to connect
to any lnd node using a pairing phrase.
How It Works
CODEBLOCK1
- 1. 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
- 4. Once connected, the agent can call any of the 18 read-only tools
- INLINECODE3 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
CODEBLOCK2
The install script builds from the lightning-mcp-server/ directory in this repo.
Configuration
CODEBLOCK3
Configuration is stored in lightning-mcp-server/.env. Key settings:
| Variable | Default | Description |
|---|
| INLINECODE6 | INLINECODE7 | Mailbox relay server |
| INLINECODE8 |
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:
CODEBLOCK4
Scope options: --scope local (default, just you), --scope project (shared
via .mcp.json), --scope user (all your projects).
Option 2: Setup script (from source)
CODEBLOCK5
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:
CODEBLOCK6
Or with a locally built binary:
CODEBLOCK7
Or run via Docker:
CODEBLOCK8
Available Tools (18)
Connection
| Tool | Description |
|---|
| INLINECODE22 | Connect to lnd via LNC pairing phrase |
| INLINECODE23 |
Close active LNC connection |
Node
| Tool | Description |
|---|
| INLINECODE24 | Node alias, version, sync status, block height |
| INLINECODE25 |
Wallet balance (on-chain) and channel balance |
Channels
| Tool | Description |
|---|
| INLINECODE26 | Active/inactive channels with capacity, balances |
| INLINECODE27 |
Channels being opened or closed |
Invoices
| Tool | Description |
|---|
| INLINECODE28 | Decode a BOLT11 invoice |
| INLINECODE29 |
List invoices with pagination |
|
lnc_lookup_invoice | Look up invoice by payment hash |
Payments
| Tool | Description |
|---|
| INLINECODE31 | Payment history with pagination |
| INLINECODE32 |
Track specific payment by hash |
Peers & Network
| Tool | Description |
|---|
| INLINECODE33 | Connected peers with stats |
| INLINECODE34 |
Lightning Network topology sample |
|
lnc_get_node_info | Detailed info about a specific node |
On-Chain
| Tool | Description |
|---|
| INLINECODE36 | UTXOs with confirmations |
| INLINECODE37 |
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:
CODEBLOCK9
Tools not appearing in Claude Code
Restart Claude Code after running
setup-claude-config.sh. Check that
lightning-mcp-server is on your
$PATH:
CODEBLOCK10
MCP LNC 服务器
构建并配置MCP服务器，通过闪电节点连接（LNC）将AI助手连接到闪电节点。LNC通过邮箱中继使用加密的WebSocket隧道，因此代理无需直接gRPC访问、TLS证书或macaroon——只需来自Lightning Terminal的10词配对短语即可。
MCP服务器默认只读——它提供18个用于查询节点状态的工具，但无法发送支付或修改通道。
快速开始
bash
1. 构建MCP服务器二进制文件
skills/lightning-mcp-server/scripts/install.sh
2. 配置环境（邮箱服务器、开发模式等）
skills/lightning-mcp-server/scripts/configure.sh
3. 作为MCP服务器添加到Claude Code
skills/lightning-mcp-server/scripts/setup-claude-config.sh
然后重启Claude Code。lnc_connect工具将可用于使用配对短语连接到任何lnd节点。
工作原理
Claude Code <--stdio--> lightning-mcp-server <--LNC WebSocket--> 邮箱 <--> lnd
- 1. Claude Code将lightning-mcp-server作为子进程启动（stdio传输）
- 代理使用配对短语和密码调用lncconnect
- 服务器生成临时ECDSA密钥对，并通过邮箱中继打开加密的WebSocket隧道
- 连接成功后，代理可以调用18个只读工具中的任意一个
- lncdisconnect关闭隧道
没有密钥、证书或macaroon存储在磁盘上——配对短语是唯一的凭证，且仅在内存中处理。
安装
bash
从源码构建（需要Go 1.24+）
skills/lightning-mcp-server/scripts/install.sh
验证
lightning-mcp-server -version
安装脚本从此仓库的lightning-mcp-server/目录构建。
配置
bash
使用默认值生成.env
skills/lightning-mcp-server/scripts/configure.sh
生产环境（通过Lightning Terminal的主网）
skills/lightning-mcp-server/scripts/configure.sh --production
开发环境（本地regtest）
skills/lightning-mcp-server/scripts/configure.sh --dev --mailbox aperture:11110
配置存储在lightning-mcp-server/.env中。关键设置：
| 变量 | 默认值 | 描述 |
|---|
| LNCMAILBOXSERVER | mailbox.terminal.lightning.today:443 | 邮箱中继服务器 |
| LNCDEVMODE |
false | 启用开发模式 |
| LNC_INSECURE | false | 跳过TLS验证（仅开发环境） |
| LNC
CONNECTTIMEOUT | 30 | 连接超时时间（秒） |
Claude Code集成
选项1：claude mcp add（推荐）
使用单个命令注册MCP服务器——无需构建步骤：
bash
通过npx零安装（下载预构建二进制文件）
claude mcp add --transport stdio lnc -- npx -y @lightninglabs/lightning-mcp-server
带环境变量的生产环境配置
claude mcp add --transport stdio \
--env LNC
MAILBOXSERVER=mailbox.terminal.lightning.today:443 \
lnc -- npx -y @lightninglabs/lightning-mcp-server
开发/regtest环境
claude mcp add --transport stdio \
--env LNC
MAILBOXSERVER=localhost:11110 \
--env LNC
DEVMODE=true \
--env LNC_INSECURE=true \
lnc -- npx -y @lightninglabs/lightning-mcp-server
作用域选项：--scope local（默认，仅您自己）、--scope project（通过.mcp.json共享）、--scope user（您的所有项目）。
选项2：设置脚本（从源码）
bash
将lightning-mcp-server添加到Claude Code的MCP配置
skills/lightning-mcp-server/scripts/setup-claude-config.sh
项目级配置（仅当前项目）
skills/lightning-mcp-server/scripts/setup-claude-config.sh --scope project
全局配置（所有项目）
skills/lightning-mcp-server/scripts/setup-claude-config.sh --scope global
这会将服务器添加到Claude Code的.mcp.json（项目）或~/.claude.json（全局）配置中。重启Claude Code后，LNC工具将可用。
选项3：手动配置
添加到项目根目录的.mcp.json：
json
{
mcpServers: {
lnc: {
command: npx,
args: [-y, @lightninglabs/lightning-mcp-server],
env: {
LNCMAILBOXSERVER: mailbox.terminal.lightning.today:443
}
}
}
}
或使用本地构建的二进制文件：
json
{
mcpServers: {
lnc: {
command: lightning-mcp-server,
env: {
LNCMAILBOXSERVER: mailbox.terminal.lightning.today:443
}
}
}
}
或通过Docker运行：
json
{
mcpServers: {
lnc: {
command: docker,
args: [
run, --rm, -i, --network, host,
--env, LNCMAILBOXSERVER,
--env, LNCDEVMODE,
--env, LNC_INSECURE,
lightning-mcp-server
]
}
}
}
可用工具（18个）
连接
| 工具 | 描述 |
|---|
| lncconnect | 通过LNC配对短语连接到lnd |
| lncdisconnect |
关闭活跃的LNC连接 |
节点
| 工具 | 描述 |
|---|
| lncgetinfo | 节点别名、版本、同步状态、区块高度 |
| lncgetbalance |
钱包余额（链上）和通道余额 |
通道
| 工具 | 描述 |
|---|
| lnclistchannels | 活跃/非活跃通道及其容量、余额 |
| lncpendingchannels |
正在开启或关闭的通道 |
发票
| 工具 | 描述 |
|---|
| lncdecodeinvoice | 解码BOLT11发票 |
| lnclistinvoices |
分页列出发票 |
| lnc
lookupinvoice | 按支付哈希查找发票 |
支付
| 工具 | 描述 |
|---|
| lnclistpayments | 带分页的支付历史 |
| lnctrackpayment |
按哈希追踪特定支付 |
对等节点与网络
| 工具 | 描述 |
|---|
| lnclistpeers | 已连接的对等节点及其统计信息 |
| lncdescribegraph |
闪电网络拓扑样本 |
| lnc
getnode_info | 特定节点的详细信息 |
链上
| 工具 | 描述 |
|---|
| lnclistunspent | 带确认数的UTXO |
| lncgettransactions |
链上交易历史 |
| lnc
estimatefee | 确认目标的手续费估算 |
安全模型
- - 无存储凭证： 配对短语仅在内存中处理。每次会话生成临时ECDSA密钥对。
- 只读： 不暴露任何支付、通道或状态变更操作。代理可以观察但不能修改。
- 加密隧道： 所有流量通过邮箱中继进行端到端加密。邮箱无法读取流量。
- 无直接访问： 代理机器从不直接连接lnd节点的gRPC端口——所有流量都通过邮箱。
与直接gRPC访问的对比
| MCP LNC服务器 | 直接lncli/gRPC |
|---|
| 凭证 | 配对短语（内存中） | TLS证书 + macaroon（磁盘上） |
| 网络 |
通过邮箱中继的WebSocket | 直接TCP到gRPC端口 |
|
防火墙 | 无需入站端口 | 端口10009必须可达 |
|
权限 | 只读（硬编码） | 取决于macaroon作用域 |
|
设置 | 来自Lightning Terminal的配对短语 | 导出证书 + macaroon文件 |
##
