Lightning MCP Server

🚀 Lightning Network MCP Server

The Lightning Network MCP Server enables Large Language Model (LLM) agents, such as those running in Goose, to query Lightning node data using natural language. It implements the Model Context Protocol (MCP) specification version 2025-03-26 and is fully compatible with MCP Inspector 1.7.0.

This server connects to your node via gRPC or Lightning Node Connect (LNC) and returns both human-readable summaries and machine-readable JSON outputs. It is designed to be modular, testable, and extensible to support additional node types, such as Core Lightning and Eclair.

For architectural details, refer to ARCHITECTURE.md.

✨ Features

This system parses natural language prompts, determines user intent, evaluates domain logic, and queries your Lightning node. Responses are returned in both plain text and structured JSON formats. Currently, it supports basic channel queries, and more extensive features, including node status, invoices, and routing data, are actively under development.

💻 Usage Examples

Basic Usage

Ask questions in natural language:

Examples:

• "How can I use the MCP server to query my Lightning wallet balance?"
• "Please list all channels associated with my address."

Important Note:

• Currently, operations to create or modify channels are not supported.
• Query scope is limited to the local data of your node.

🚀 Quick Start

Connecting to an LND Node

Using Default Configuration

Create a .env file in the project root directory and add the following content:

# Direct connection using gRPC (recommended)
LND_GRPC_HOST=127.0.0.1
LND_GRPC_PORT=10009
MACAROON_FILE=./macaroon.pem
CERTIFICATE_FILE=./cert.pem

# Or remote connection using LNC
LNC_SERVER_HOST=127.0.0.1
LNC_SERVER_PORT=8080

Using the Credential Extraction Tool

If your device supports -lndconnect URLs, run the following command:

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

This script will:

1. Extract the host, port, certificate, and macaroon.
2. Convert the certificate to PEM format (required format).
3. Save the files to the test/fixtures directory.
4. Output the configuration to be added to the .env file.

Testing with the MCP Inspector

To test using the official MCP Inspector:

1. Install the inspector:

   npm install -g @modelcontextprotocol/inspector
   

2. Build the project:

   npm run build
   

3. Run the inspection:

   LOG_LEVEL=warn npx @modelcontextprotocol/inspector node scripts/inspect.js
   

📚 Documentation

Compatibility

• MCP specification version 2025-03-26
• MCP Inspector version 1.7.0
• Compatible with MCP agents (e.g., Goose)
• Supports direct node access via gRPC
• Supports remote secure access via LNC
• Provides JSON and natural language output formats

🤝 Contribution

For guidance on setup, styling, and testing, refer to CONTRIBUTING.md.

📄 License

This project is licensed under the Apache License 2.0. See LICENSE for details.