LNbits MCP Server

A Model Context Protocol (MCP) server for LNbits Lightning Network wallet integration. This server allows AI assistants to interact with LNbits through a comprehensive set of tools for wallet management, payments, invoices, and extensions.

💡 Examples

Basic Usage with an AI Assistant

Once configured, you can interact with your LNbits wallet through your favorite AI assistant.

"Check my wallet balance"
"Create an invoice for 1000 sats with memo 'Coffee payment'"
"Pay this invoice: lnbc10u1p3..."
"Send 500 sats to [email protected]"
"Pay Lightning address [email protected] 1000 sats with comment 'Thanks for the coffee!'"
"Show me my recent payments"
"What's the status of payment hash abc123..."

🚀 Features

⚡ Core Wallet Operations: Get wallet details, balance, and transaction history
💸 Payment Management: Send Lightning payments and check payment status
🧾 Invoice Creation: Create and manage Lightning invoices
🔌 Extension Support: Integrate with popular LNbits extensions (LNURLp, TPoS, SatsPay, etc.)
🔧 Admin Tools: User and node management capabilities
🔒 Secure Authentication: Support for API keys, Bearer tokens, and OAuth2
📝 Type Safety: Full type hints and Pydantic models
📊 Structured Logging: Comprehensive logging with structlog
🚦 Rate Limiting: Built-in request throttling

📦 Installation

From Source

git clone https://github.com/your-repo/lnbits-mcp-server
cd lnbits-mcp-server
pip install -e .

Development Installation

git clone https://github.com/your-repo/lnbits-mcp-server
cd lnbits-mcp-server
pip install -e .[dev]

⚙️ Configuration

Runtime Configuration (Recommended)

The LNbits MCP server supports runtime configuration through MCP tools, allowing you to configure the server directly from your LLM client without needing to modify environment variables or restart the server.

Configure lnbits.

URL: https://demo.lnbits.com
Key: [your api key]
Auth method: api_key_header

Available configuration tools:

configure_lnbits - Configure LNbits connection parameters at runtime
get_lnbits_configuration - Get current configuration status
test_lnbits_configuration - Test the current configuration

Environment Variables (Legacy)

The server still supports environment variable configuration for backward compatibility:

# LNbits instance URL
LNBITS_URL=https://your-lnbits-instance.com

# Authentication (choose one method)
LNBITS_API_KEY=your_api_key_here
LNBITS_BEARER_TOKEN=your_bearer_token
LNBITS_OAUTH2_TOKEN=your_oauth2_token

# Authentication method (optional, defaults to api_key_header)
LNBITS_AUTH_METHOD=api_key_header  # or api_key_query, http_bearer, oauth2

# Request settings (optional)
LNBITS_TIMEOUT=30
LNBITS_MAX_RETRIES=3
LNBITS_RATE_LIMIT_PER_MINUTE=60

Configuration Reference

Variable	Description	Default	Required
`LNBITS_URL`	Base URL for LNbits instance	`https://demo.lnbits.com`	No
`LNBITS_API_KEY`	API key for authentication	`None`	Yes*
`LNBITS_BEARER_TOKEN`	Bearer token for authentication	`None`	Yes*
`LNBITS_OAUTH2_TOKEN`	OAuth2 token for authentication	`None`	Yes*
`LNBITS_AUTH_METHOD`	Authentication method	`api_key_header`	No
`LNBITS_TIMEOUT`	Request timeout in seconds	`30`	No
`LNBITS_MAX_RETRIES`	Maximum request retries	`3`	No
`LNBITS_RATE_LIMIT_PER_MINUTE`	Rate limit per minute	`60`	No

*At least one authentication method must be provided.

🚀 Usage

Running the Server

# Using the installed command
lnbits-mcp-server

# Or run directly with Python
python -m lnbits_mcp_server.server

Claude Desktop Integration

For Claude Desktop, add to your claude_desktop_config.json:

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

{
  "mcpServers": {
    "lnbits": {
      "command": "/Users/[username]/Desktop/lnbits-mcp-server/venv/bin/lnbits-mcp-server"
    }
  }
}

Note: With runtime configuration, you no longer need to set environment variables in the config file. Configure the server directly through your LLM client after setup.

Other MCP Clients

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "lnbits": {
      "command": "lnbits-mcp-server"
    }
  }
}

Note: With runtime configuration, you can configure the server directly through your MCP client after setup.

🛠️ Available Tools

Configuration Tools

configure_lnbits - Configure LNbits connection parameters at runtime
get_lnbits_configuration - Get current configuration status
test_lnbits_configuration - Test the current configuration

Core Wallet Tools

get_wallet_details - Get wallet information including balance and keys
get_wallet_balance - Get current wallet balance
get_payments - Get payment history
check_connection - Test connection to LNbits instance

Payment Tools

pay_invoice - Pay a Lightning invoice (BOLT11)
pay_lightning_address - Pay a Lightning address (e.g., [email protected])
get_payment_status - Check payment status by hash
decode_invoice - Decode and analyze a Lightning invoice

Invoice Tools

create_invoice - Create a new Lightning invoice

Extension Tools (if extensions are enabled)

create_lnurlp_link - Create LNURLp pay links
get_lnurlp_links - List LNURLp pay links
create_tpos - Create TPoS terminals
get_tpos_list - List TPoS terminals
create_satspay_charge - Create SatsPay charges
get_satspay_charges - List SatsPay charges
create_watchonly_wallet - Create watch-only wallets
get_watchonly_wallets - List watch-only wallets

Admin Tools (if admin access is available)

get_node_info - Get Lightning node information
list_users - List all users
create_user - Create new users
get_system_stats - Get system statistics

API Usage

from lnbits_mcp_server.client import LNbitsClient

async def example():
    client = LNbitsClient()
    
    # Get wallet balance
    balance = await client.get_wallet_balance()
    print(f"Current balance: {balance['balance']} msats")
    
    # Create an invoice
    invoice = await client.create_invoice(
        amount=1000,  # 1000 sats
        memo="Test payment"
    )
    print(f"Invoice: {invoice['bolt11']}")
    
    # Pay an invoice
    payment = await client.pay_invoice("lnbc1...")
    print(f"Payment hash: {payment['payment_hash']}")
    
    # Pay a Lightning address
    lightning_payment = await client.pay_lightning_address(
        lightning_address="[email protected]",
        amount_sats=1000,
        comment="Payment via Lightning address"
    )
    print(f"Lightning address payment hash: {lightning_payment['payment_hash']}")

🔧 Development

Setting up Development Environment

git clone https://github.com/your-repo/lnbits-mcp-server
cd lnbits-mcp-server
pip install -e .[dev]

Running Tests

pytest

Code Quality

# Format code
black src tests
isort src tests

# Type checking
mypy src

Testing with Claude Desktop

Configure the server in your Claude Desktop config
Restart Claude Desktop

Configure your LNbits connection:

Configure lnbits.

URL: https://demo.lnbits.com
Key: [your api key]
Auth method: api_key_header

Test with commands like:
- "Check my LNbits connection"
- "What's my wallet balance?"
- "Create a 100 sat invoice"
- "Send 21 sats to [email protected]"
- "Pay Lightning address [email protected] 500 sats"

🏗️ Architecture

The server follows a modular architecture:

server.py: Main MCP server implementation
client.py: HTTP client for LNbits API
tools/: Tool implementations organized by functionality
- core.py: Wallet operations
- payments.py: Payment processing
- invoices.py: Invoice management
- extensions.py: Extension integrations
- admin.py: Administrative tools
models/: Pydantic data models
utils/: Utility functions and authentication

🔒 Security Considerations

API Keys: Store API keys securely using environment variables
Network Security: Use HTTPS for production LNbits instances
Access Control: Limit API key permissions to required operations only
Rate Limiting: Built-in rate limiting prevents API abuse
Logging: Sensitive information is not logged

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Run the test suite
Submit a pull request

📄 License

MIT License - see LICENSE file for details.

📞 Support

Issues: GitHub Issues
Documentation: GitHub Wiki
LNbits: Official Documentation

📝 Changelog

v0.1.0

✅ Initial release
✅ Core wallet operations (balance, details, payments)
✅ Payment processing (pay invoices, check status)
✅ Lightning address payments (pay [email protected] addresses)
✅ Invoice creation and management
✅ Comprehensive error handling and structured logging
✅ Claude Desktop integration
✅ Type safety with Pydantic models
✅ Rate limiting and authentication support

🎯 Quick Start

Install: pip install -e .
Add to Claude: Update your claude_desktop_config.json
Configure: Use runtime configuration through your LLM client
Test: Ask Claude to check your wallet balance
Enjoy: Lightning-fast Bitcoin payments through AI! ⚡

For detailed setup instructions, see QUICK_START.md

Built with ❤️ for the Bitcoin Lightning Network community

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
src/lnbits_mcp_server		src/lnbits_mcp_server
.env		.env
.gitignore		.gitignore
QUICK_START.md		QUICK_START.md
README.md		README.md
claude_desktop_config.json		claude_desktop_config.json
mcp_config_example.json		mcp_config_example.json
openapi.json		openapi.json
openapi.yaml		openapi.yaml
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
test_claude_connection.py		test_claude_connection.py
test_lightning_address.py		test_lightning_address.py
test_simple_mcp.py		test_simple_mcp.py

lnbits/LNbits-MCP-Server

Folders and files

Latest commit

History

Repository files navigation