MCP Server

February 10, 2026 · View on GitHub

Connecting AI assistants to Lightning nodes through the Model Context Protocol and Lightning Node Connect.

Lightning Agent Tools includes an MCP server that gives AI assistants read-only access to a Lightning node. It uses Lightning Node Connect (LNC) for transport, which means the assistant never needs direct network access to the node, never handles TLS certificates, and never stores macaroons on disk. A 10-word pairing phrase is all it takes to establish an encrypted tunnel.

The server exposes 18 tools, all read-only, that let an assistant query node status, inspect channels, decode invoices, look up payments, and explore the network graph. It cannot send payments, open channels, or modify any node state.

How LNC Works

Lightning Node Connect establishes an end-to-end encrypted WebSocket tunnel between two parties through a mailbox relay server. Both the MCP server (on the agent's machine) and the lnd node (running Lightning Terminal) connect outbound to the mailbox. Neither needs to accept inbound connections, which means no firewall configuration and no port forwarding.

graph LR
    CC["Claude Code<br/>(stdio)"] <--> MCP["lightning-mcp-server"]
    MCP <-->|"encrypted<br/>WebSocket"| MB["Mailbox Relay<br/>mailbox.terminal.lightning.today"]
    MB <-->|"encrypted<br/>WebSocket"| LND["lnd + Lightning Terminal"]

    style MB fill:#f5f5f5,stroke:#999

Authentication works through a 10-word pairing phrase generated in Lightning Terminal. When the MCP server connects, it generates an ephemeral ECDSA keypair, uses the pairing phrase to derive a shared secret, and establishes the encrypted tunnel. The keypair exists only in memory for the duration of the session -- when the connection closes, the keypair is discarded and no credentials remain on disk.

The mailbox relay cannot read the traffic passing through it. It sees encrypted WebSocket frames and routes them between the two endpoints based on connection identifiers derived from the pairing phrase.

Setup

Three scripts handle the full setup:

1. Build the server

skills/lightning-mcp-server/scripts/install.sh

This compiles lightning-mcp-server from the lightning-mcp-server/ directory in the repository and installs it to $GOPATH/bin. Requires Go 1.24+.

2. Configure the environment

# Production (Lightning Terminal on mainnet)
skills/lightning-mcp-server/scripts/configure.sh --production

# Development (local regtest)
skills/lightning-mcp-server/scripts/configure.sh --dev --mailbox aperture:11110

This generates lightning-mcp-server/.env with the following variables:

Variable	Default	Description
`LNC_MAILBOX_SERVER`	`mailbox.terminal.lightning.today:443`	Mailbox relay address
`LNC_DEV_MODE`	`false`	Enable development mode
`LNC_INSECURE`	`false`	Skip TLS verification (dev only)
`LNC_CONNECT_TIMEOUT`	`30`	Connection timeout in seconds

3. Register with Claude Code

# Project-level (recommended)
skills/lightning-mcp-server/scripts/setup-claude-config.sh --scope project

# Global
skills/lightning-mcp-server/scripts/setup-claude-config.sh --scope global

This adds the MCP server to .mcp.json (project) or ~/.claude.json (global). Restart Claude Code after running this script for the new tools to appear.

The resulting configuration looks like:

{
  "mcpServers": {
    "lnc": {
      "command": "lightning-mcp-server",
      "env": {
        "LNC_MAILBOX_SERVER": "mailbox.terminal.lightning.today:443"
      }
    }
  }
}

4. Connect

After restarting Claude Code, the lnc_connect tool becomes available. Connect with a pairing phrase from Lightning Terminal:

Connect to my Lightning node with pairing phrase: "word1 word2 word3 word4 word5 word6 word7 word8 word9 word10"

The assistant will call lnc_connect, establish the tunnel, and then all 18 read-only tools become operational.

Available Tools

The server organizes its 18 tools into seven categories:

Connection

Tool	Description
`lnc_connect`	Establish LNC tunnel with a pairing phrase and password
`lnc_disconnect`	Close the active tunnel and discard the ephemeral keypair

Node

Tool	Description
`lnc_get_info`	Node alias, public key, version, sync status, current block height
`lnc_get_balance`	On-chain wallet balance and total channel balance

Channels

Tool	Description
`lnc_list_channels`	All open channels with capacity, local/remote balances, and activity
`lnc_pending_channels`	Channels being opened, closed, or force-closed

Invoices

Tool	Description
`lnc_decode_invoice`	Decode a BOLT11 payment request into its components
`lnc_list_invoices`	Paginated list of created invoices with status
`lnc_lookup_invoice`	Look up a specific invoice by payment hash

Payments

Tool	Description
`lnc_list_payments`	Paginated payment history with status, amounts, and routes
`lnc_track_payment`	Track a specific in-flight or completed payment by hash

Peers and Network

Tool	Description
`lnc_list_peers`	Connected peers with addresses, bytes sent/received, and ping times
`lnc_describe_graph`	Sample of the Lightning Network topology (nodes and channels)
`lnc_get_node_info`	Detailed information about a specific node by public key

On-Chain

Tool	Description
`lnc_list_unspent`	Unspent transaction outputs (UTXOs) with confirmation counts
`lnc_get_transactions`	On-chain transaction history
`lnc_estimate_fee`	Fee rate estimates for target confirmation windows

MCP-LNC vs Direct gRPC

The MCP server and direct gRPC access (via lncli or the lnd skill) serve different purposes:

	MCP-LNC	Direct gRPC
Credentials	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
Capabilities	Read-only (18 query tools)	Full node control
Permissions	Hardcoded read-only	Configurable via macaroon scope
Setup	Pairing phrase from Lightning Terminal	Export TLS cert and macaroon files

Use MCP-LNC when the agent only needs to observe node state: checking balances, listing channels, monitoring payments, inspecting the network graph. The read-only constraint and lack of stored credentials make it the safest option for giving an AI assistant access to node data.

Use direct gRPC when the agent needs to perform actions: sending payments, opening channels, creating invoices. Direct gRPC requires the lnd skill and appropriate macaroons (scoped via macaroon-bakery).

Server Internals

The MCP server is a Go application in the lightning-mcp-server/ directory. It runs on stdio transport. The MCP client launches it as a subprocess and communicates over stdin/stdout.

The entry point (daemon.go) handles signal-based shutdown (SIGINT, SIGTERM) with a graceful timeout. The server (server.go) initializes a service manager (internal/services/manager.go) that creates one service per tool category and registers all 18 tools with the MCP Go SDK.

When lnc_connect is called, the manager creates a Lightning client using the LNC library (github.com/lightninglabs/lightning-node-connect/mailbox), establishes the tunnel, and distributes the client to all services via the onLNCConnectionEstablished callback. When lnc_disconnect is called, the connection is closed and all services are reset.

Building from Source

cd lightning-mcp-server
make build           # debug binary
make build-release   # optimized binary
make install         # install to $GOPATH/bin
make check           # run fmt, lint, mod-check, and unit tests

Docker

For containerized deployment:

cd lightning-mcp-server
make docker-build

The Docker configuration in .mcp.json:

{
  "mcpServers": {
    "lnc": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network", "host",
        "--env", "LNC_MAILBOX_SERVER",
        "--env", "LNC_DEV_MODE",
        "--env", "LNC_INSECURE",
        "lightning-mcp-server"
      ]
    }
  }
}

Development Setup

For local regtest environments, enable development mode to skip TLS verification and connect to a local mailbox:

skills/lightning-mcp-server/scripts/configure.sh --dev --mailbox localhost:11110 --insecure

This sets LNC_DEV_MODE=true and LNC_INSECURE=true in the .env file.

Prerequisites

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

Troubleshooting

"pairing phrase must be exactly 10 words": The pairing phrase is generated in Lightning Terminal's Sessions UI. It must be exactly 10 space-separated words.

"connection timeout": Verify the mailbox server is reachable. For production, this is mailbox.terminal.lightning.today:443. For local development, ensure the local mailbox is running.

"TLS handshake failure": For local regtest, enable 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. Verify the binary is on your PATH with which lightning-mcp-server.