LND MCP Server

Created By

pblittle9 months ago

A Model Context Protocol (MCP) for querying Lightning Network (LND) node data using natural language.

Content

LND MCP Server

A Model Context Protocol (MCP)-compatible server for interacting with your Lightning Network Daemon (LND) node. This server provides a natural language interface to query your LND node through the Model Context Protocol, allowing AI assistants to safely interact with your node data.

This MCP server can be used with any LLM application that supports the Model Context Protocol, including Block Goose, Claude, and OpenAI-based applications.

Prerequisites

Node.js (v14 or later)
npm (v6 or later)
Access to an LND node (local or remote)

Installation

Clone the repository
Install dependencies:
```
npm install
```
Set up your environment (see Environment Management below)
Build the project:
```
npm run build
```

Environment Management

This project uses a clean, flexible environment management system that allows both standardized environment configurations and developer-specific customizations.

Environment Files

The system uses a cascading hierarchy of environment files:

.env.[environment].local - Not committed, developer-specific overrides
.env.[environment] - Committed, shared environment-specific settings
.env.local - Not committed, shared local settings
.env - Committed, default settings

Files higher in the list take precedence over those lower in the list.

Environment Types

The application supports these environment types:

development - For local development
test - For automated testing
production - For production use

Usage

Simply set the NODE_ENV environment variable to switch between environments:

# Development mode
NODE_ENV=development npm run mcp

# Test mode
NODE_ENV=test npm run mcp

# Production mode
NODE_ENV=production npm run mcp

Or use the convenience scripts:

# Development mode
npm run mcp:dev

# Test mode
npm run mcp:test

# Production mode
npm run mcp:prod

Local Overrides

For developer-specific settings (like paths to your specific LND node):

Create a file named .env.[environment].local
Add your custom settings
This file won't be committed to Git

Example .env.development.local:

# My custom LND settings
LND_TLS_CERT_PATH=/Users/myname/.lnd/tls.cert
LND_MACAROON_PATH=/Users/myname/.lnd/data/chain/bitcoin/mainnet/readonly.macaroon

Mock LND Mode

Set USE_MOCK_LND=true in any environment file to use a mock LND setup. This is useful for development and testing without a real LND node.

LND Configuration

This server connects to your LND node to retrieve information. You'll need:

TLS Certificate: Typically located at ~/.lnd/tls.cert
Macaroon: Use a readonly macaroon for security, typically at ~/.lnd/data/chain/bitcoin/mainnet/readonly.macaroon
Host and Port: Default is localhost:10009

These values can be set in your environment files as described above.

Running the Server

Start the server in development mode (with mock LND):

npm run mcp:dev

For production use with a real LND node:

npm run mcp:prod

MCP Server Features

Natural Language LND Queries

The MCP server provides a powerful natural language query interface for your LND node. This allows you to interact with your node using simple, conversational language instead of remembering specific commands and parameters.

Currently Supported: Channel Queries

The first implementation focuses on comprehensive channel queries:

"Show me all my channels"
"What's the health of my channels?"
"How is my channel liquidity distributed?"

These queries provide detailed information about your channels, including capacity, balance, status, health analysis, and liquidity distribution.

Future Expansions

The architecture is designed for easy expansion to include:

Node queries: Information about connected nodes, network position, etc.
Transaction queries: Payment history, routing information, fee analysis
Network queries: Network graph insights, route planning, path discovery

Benefits

Intuitive: No need to remember specific command syntax
Contextual: Responses are formatted in an easy-to-understand way
Comprehensive: Get detailed information with simple queries
Flexible: Multiple ways to ask for the same information
Expandable: Architecture designed to add more query capabilities

Testing

Channel Query Tests

Test the natural language channel query functionality:

# Start the mock server
node scripts/mock-server.js

# In another terminal, run the test scripts
node test/channel-queries/list.js
node test/channel-queries/health.js
node test/channel-queries/liquidity.js

Each test script demonstrates a different type of natural language query:

Channel List: Shows all channels with capacity and status
Channel Health: Identifies inactive or problematic channels
Liquidity Distribution: Shows the balance between local and remote liquidity

Automated Tests

Run the test suite:

npm test

Or use the Makefile:

make test

The test suite includes:

Unit tests for LND client connection
Unit tests for natural language processing and query handling
Mocked LND responses for deterministic testing

Tests use Jest and follow a consistent pattern of mocking external dependencies while testing the full integration between components. For more details on the testing strategy, see the Architecture documentation.

Testing with Mock Server

You can run the MCP server with a mocked LND connection for testing purposes without needing a real LND node:

npm run mcp:mock

This will:

Create mock TLS certificate and macaroon files in a mock directory
Start the MCP server with a mock LND client that returns predefined responses
Allow you to test the natural language queries without a real LND connection

To test specific query types, use the provided test scripts:

# Test channel listing
node test/channel-queries/list.js

# Test channel health analysis
node test/channel-queries/health.js

# Test channel liquidity distribution
node test/channel-queries/liquidity.js

These scripts demonstrate how to:

Connect to the mock server
Send a natural language query
Parse and display the response
Extract both the human-readable text and structured JSON data

Each script focuses on a different type of query, showing how the server handles various intents:

List script: "Show me all my channels"
Health script: "What is the health of my channels?"
Liquidity script: "How is my channel liquidity distributed?"

MCP Inspector Testing

For a simplified testing experience with the MCP Inspector, you can:

Install the MCP Inspector if you haven't already:

npm install -g @modelcontextprotocol/inspector

Start the mock server:
```
node scripts/mock-server.js
```
In another terminal, run the MCP Inspector:
```
npx @modelcontextprotocol/inspector
```
In the MCP Inspector web interface:
- Click "Connect" in the top right
- Set the transport type to "stdio"
- Set the command to the path to your scripts/mock-server.js file
- Click "Connect"
Once connected, you can:
- List available tools
- Try natural language queries
- See the human-friendly responses and structured data