Lightning Node MCP server for AI agents

The Lightning Network MCP Server implements the Model Context Protocol to allow large language models to query Lightning node data using natural language. It connects to your Lightning node via gRPC or Lightning Node Connect (LNC) and provides both human-readable summaries and structured JSON responses for applications and agents.

Installation

Prerequisites

Before installing, make sure you have:

Node.js installed
Access to a Lightning Network node (LND)
Proper node credentials (TLS certificate and macaroon)

Basic Setup

Clone the repository and set up the environment:

git clone [repository-url]
cd lightning-network-mcp-server
cp .env.example .env

Configure your .env file with your LND credentials
Install dependencies and run the server:

npm install
npm run mcp:prod

Connecting to an LND Node over Tor

To connect to a Lightning node running as a Tor hidden service:

Install and start Tor on your system:

# macOS (using Homebrew)
brew install tor
brew services start tor

# Ubuntu/Debian
sudo apt install tor
sudo systemctl start tor

Configure your .env file with Tor SOCKS proxy settings:

CONNECTION_TYPE=lnd-direct
LND_HOST=your-node-address.onion
LND_PORT=10009
LND_TLS_CERT_PATH=/path/to/tls.pem
LND_MACAROON_PATH=/path/to/admin.macaroon
SOCKS_PROXY_HOST=localhost
SOCKS_PROXY_PORT=9050

Ensure your TLS certificate is in PEM format (begins with -----BEGIN CERTIFICATE-----).

Using the Credential Extraction Tool

If you have an lndconnect URL (commonly used in mobile apps), you can extract the credentials:

# Extract from an lndconnect URL
node scripts/extract-credentials.js "lndconnect://your-node.onion:10009?cert=BASE64CERT&macaroon=BASE64MACAROON"

# Or set LNDCONNECT_URL in your .env file and run
node scripts/extract-credentials.js

This tool will extract the host, port, certificate, and macaroon, convert the certificate to PEM format, save the files, and print configuration for your .env file.

Usage

Basic Queries

Once the server is running, you can query your Lightning node using natural language. For example:

Show me my channels

The server will respond with human-readable text:

Your node has 5 channels with a total capacity of 0.05000000 BTC (5,000,000 sats).
4 channels are active and 1 is inactive.

Your channels:
1. ACINQ: 0.02000000 BTC (2,000,000 sats) (active)
2. Bitrefill: 0.01000000 BTC (1,000,000 sats) (active)
3. LightningTipBot: 0.00800000 BTC (800,000 sats) (active)
4. Wallet of Satoshi: 0.00700000 BTC (700,000 sats) (active)
5. LN+: 0.00500000 BTC (500,000 sats) (inactive)

Along with structured JSON for applications:

{
  "channels": [
    {
      "remote_alias": "ACINQ",
      "capacity": 2000000,
      "local_balance": 800000,
      "active": true
    },
    ...
  ],
  "summary": {
    "total_capacity": 5000000,
    "active_channels": 4,
    "inactive_channels": 1,
    "largest_channel_alias": "ACINQ",
    "average_local_balance": 750000
  }
}

Currently Supported Features

The server currently supports basic channel queries like:

"Show me my channels"

Additional features in development include:

Channels: "What is the health of my channels?", "Do I have any inactive channels?"
Invoices: "How many invoices have I received this week?", "What was my last payment?"
Nodes: "What node am I connected to the most?", "What node did I last forward a payment to?"
Routing: "How much have I routed in the last 24 hours?", "Which channels are doing most of the routing?"

Testing with MCP Inspector

To test the server using the official MCP inspector:

npm install -g @modelcontextprotocol/inspector
npm run build
LOG_LEVEL=warn npx @modelcontextprotocol/inspector node scripts/inspect.js

Compatibility

The server is compatible with:

MCP Specification version 2025-03-26
MCP Inspector version 1.7.0
MCP agents (e.g., Goose)
Direct node access via gRPC
Secure remote access via LNC
Both JSON and natural-language output formats

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "lightning-node" '{"command":"npm","args":["run","mcp:prod"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "lightning-node": {
            "command": "npm",
            "args": [
                "run",
                "mcp:prod"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "lightning-node": {
            "command": "npm",
            "args": [
                "run",
                "mcp:prod"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect