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.

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 bc@sats.pw" "Pay Lightning address alice@lnbits.com 1000 sats with comment 'Thanks for the coffee!'" "Show me my recent payments" "What's the status of payment hash abc123..." 

• ⚡ 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

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

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

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

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

*At least one authentication method must be provided.

# Using the installed command lnbits-mcp-server # Or run directly with Python python -m lnbits_mcp_server.server

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.

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.

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

• 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

• pay_invoice - Pay a Lightning invoice (BOLT11)
• pay_lightning_address - Pay a Lightning address (e.g., user@domain.com)
• get_payment_status - Check payment status by hash
• decode_invoice - Decode and analyze a Lightning invoice

• create_invoice - Create a new Lightning invoice

• 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

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

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="edward@sats.pw", amount_sats=1000, comment="Payment via Lightning address" ) print(f"Lightning address payment hash: {lightning_payment['payment_hash']}")

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

pytest

# Format code black src tests isort src tests # Type checking mypy src

1. Configure the server in your Claude Desktop config
2. Restart Claude Desktop
3. Configure your LNbits connection:

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

4. Test with commands like:
   • "Check my LNbits connection"
   • "What's my wallet balance?"
   • "Create a 100 sat invoice"
   • "Send 21 sats to edward@sats.pw"
   • "Pay Lightning address alice@getalby.com 500 sats"

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

• 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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run the test suite
6. Submit a pull request

MIT License - see LICENSE file for details.

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

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

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

For detailed setup instructions, see QUICK_START.md

Built with ❤️ for the Bitcoin Lightning Network community