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. - ⚡ Core Wallet Operations: Get wallet details, balance, and trans
Add this skill
npx mdskills install lnbits/lnbits-mcp-serverComprehensive Lightning Network integration with runtime configuration and extensive wallet management tools
1# LNbits MCP Server23A Model Context Protocol (MCP) server for [LNbits](https://lnbits.com/) 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.45## 💡 Examples67### Basic Usage with an AI Assistant89Once configured, you can interact with your LNbits wallet through your favorite AI assistant.1011```12"Check my wallet balance"13"Create an invoice for 1000 sats with memo 'Coffee payment'"14"Pay this invoice: lnbc10u1p3..."15"Send 500 sats to bc@sats.pw"16"Pay Lightning address alice@lnbits.com 1000 sats with comment 'Thanks for the coffee!'"17"Show me my recent payments"18"What's the status of payment hash abc123..."19```2021## 🚀 Features2223- **⚡ Core Wallet Operations**: Get wallet details, balance, and transaction history24- **💸 Payment Management**: Send Lightning payments and check payment status25- **🧾 Invoice Creation**: Create and manage Lightning invoices26- **🔌 Extension Support**: Integrate with popular LNbits extensions (LNURLp, TPoS, SatsPay, etc.)27- **🔧 Admin Tools**: User and node management capabilities28- **🔒 Secure Authentication**: Support for API keys, Bearer tokens, and OAuth229- **📝 Type Safety**: Full type hints and Pydantic models30- **📊 Structured Logging**: Comprehensive logging with structlog31- **🚦 Rate Limiting**: Built-in request throttling3233## 📦 Installation3435### From Source3637```bash38git clone https://github.com/your-repo/lnbits-mcp-server39cd lnbits-mcp-server40pip install -e .41```4243### Development Installation4445```bash46git clone https://github.com/your-repo/lnbits-mcp-server47cd lnbits-mcp-server48pip install -e .[dev]49```5051## ⚙️ Configuration5253### Runtime Configuration (Recommended)5455The 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.5657```58Configure lnbits.5960URL: https://demo.lnbits.com61Key: [your api key]62Auth method: api_key_header63```6465Available configuration tools:66- `configure_lnbits` - Configure LNbits connection parameters at runtime67- `get_lnbits_configuration` - Get current configuration status68- `test_lnbits_configuration` - Test the current configuration6970### Environment Variables (Legacy)7172The server still supports environment variable configuration for backward compatibility:7374```bash75# LNbits instance URL76LNBITS_URL=https://your-lnbits-instance.com7778# Authentication (choose one method)79LNBITS_API_KEY=your_api_key_here80LNBITS_BEARER_TOKEN=your_bearer_token81LNBITS_OAUTH2_TOKEN=your_oauth2_token8283# Authentication method (optional, defaults to api_key_header)84LNBITS_AUTH_METHOD=api_key_header # or api_key_query, http_bearer, oauth28586# Request settings (optional)87LNBITS_TIMEOUT=3088LNBITS_MAX_RETRIES=389LNBITS_RATE_LIMIT_PER_MINUTE=6090```9192### Configuration Reference9394| Variable | Description | Default | Required |95|----------|-------------|---------|----------|96| `LNBITS_URL` | Base URL for LNbits instance | `https://demo.lnbits.com` | No |97| `LNBITS_API_KEY` | API key for authentication | `None` | Yes* |98| `LNBITS_BEARER_TOKEN` | Bearer token for authentication | `None` | Yes* |99| `LNBITS_OAUTH2_TOKEN` | OAuth2 token for authentication | `None` | Yes* |100| `LNBITS_AUTH_METHOD` | Authentication method | `api_key_header` | No |101| `LNBITS_TIMEOUT` | Request timeout in seconds | `30` | No |102| `LNBITS_MAX_RETRIES` | Maximum request retries | `3` | No |103| `LNBITS_RATE_LIMIT_PER_MINUTE` | Rate limit per minute | `60` | No |104105*At least one authentication method must be provided.106107## 🚀 Usage108109### Running the Server110111```bash112# Using the installed command113lnbits-mcp-server114115# Or run directly with Python116python -m lnbits_mcp_server.server117```118119### Claude Desktop Integration120121For Claude Desktop, add to your `claude_desktop_config.json`:122123**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`124**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`125126```json127{128 "mcpServers": {129 "lnbits": {130 "command": "/Users/[username]/Desktop/lnbits-mcp-server/venv/bin/lnbits-mcp-server"131 }132 }133}134```135136*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.*137138### Other MCP Clients139140Add the server to your MCP client configuration:141142```json143{144 "mcpServers": {145 "lnbits": {146 "command": "lnbits-mcp-server"147 }148 }149}150```151152*Note: With runtime configuration, you can configure the server directly through your MCP client after setup.*153154## 🛠️ Available Tools155156### Configuration Tools157158- `configure_lnbits` - Configure LNbits connection parameters at runtime159- `get_lnbits_configuration` - Get current configuration status160- `test_lnbits_configuration` - Test the current configuration161162### Core Wallet Tools163164- `get_wallet_details` - Get wallet information including balance and keys165- `get_wallet_balance` - Get current wallet balance166- `get_payments` - Get payment history167- `check_connection` - Test connection to LNbits instance168169### Payment Tools170171- `pay_invoice` - Pay a Lightning invoice (BOLT11)172- `pay_lightning_address` - Pay a Lightning address (e.g., user@domain.com)173- `get_payment_status` - Check payment status by hash174- `decode_invoice` - Decode and analyze a Lightning invoice175176### Invoice Tools177178- `create_invoice` - Create a new Lightning invoice179180### Extension Tools (if extensions are enabled)181182- `create_lnurlp_link` - Create LNURLp pay links183- `get_lnurlp_links` - List LNURLp pay links184- `create_tpos` - Create TPoS terminals185- `get_tpos_list` - List TPoS terminals186- `create_satspay_charge` - Create SatsPay charges187- `get_satspay_charges` - List SatsPay charges188- `create_watchonly_wallet` - Create watch-only wallets189- `get_watchonly_wallets` - List watch-only wallets190191### Admin Tools (if admin access is available)192193- `get_node_info` - Get Lightning node information194- `list_users` - List all users195- `create_user` - Create new users196- `get_system_stats` - Get system statistics197198### API Usage199200```python201from lnbits_mcp_server.client import LNbitsClient202203async def example():204 client = LNbitsClient()205206 # Get wallet balance207 balance = await client.get_wallet_balance()208 print(f"Current balance: {balance['balance']} msats")209210 # Create an invoice211 invoice = await client.create_invoice(212 amount=1000, # 1000 sats213 memo="Test payment"214 )215 print(f"Invoice: {invoice['bolt11']}")216217 # Pay an invoice218 payment = await client.pay_invoice("lnbc1...")219 print(f"Payment hash: {payment['payment_hash']}")220221 # Pay a Lightning address222 lightning_payment = await client.pay_lightning_address(223 lightning_address="edward@sats.pw",224 amount_sats=1000,225 comment="Payment via Lightning address"226 )227 print(f"Lightning address payment hash: {lightning_payment['payment_hash']}")228```229230## 🔧 Development231232### Setting up Development Environment233234```bash235git clone https://github.com/your-repo/lnbits-mcp-server236cd lnbits-mcp-server237pip install -e .[dev]238```239240### Running Tests241242```bash243pytest244```245246### Code Quality247248```bash249# Format code250black src tests251isort src tests252253# Type checking254mypy src255```256257### Testing with Claude Desktop2582591. Configure the server in your Claude Desktop config2602. Restart Claude Desktop2613. Configure your LNbits connection:262 ```263 Configure lnbits.264265 URL: https://demo.lnbits.com266 Key: [your api key]267 Auth method: api_key_header268 ```2694. Test with commands like:270 - "Check my LNbits connection"271 - "What's my wallet balance?"272 - "Create a 100 sat invoice"273 - "Send 21 sats to edward@sats.pw"274 - "Pay Lightning address alice@getalby.com 500 sats"275276## 🏗️ Architecture277278The server follows a modular architecture:279280- **`server.py`**: Main MCP server implementation281- **`client.py`**: HTTP client for LNbits API282- **`tools/`**: Tool implementations organized by functionality283 - `core.py`: Wallet operations284 - `payments.py`: Payment processing285 - `invoices.py`: Invoice management286 - `extensions.py`: Extension integrations287 - `admin.py`: Administrative tools288- **`models/`**: Pydantic data models289- **`utils/`**: Utility functions and authentication290291## 🔒 Security Considerations292293- **API Keys**: Store API keys securely using environment variables294- **Network Security**: Use HTTPS for production LNbits instances295- **Access Control**: Limit API key permissions to required operations only296- **Rate Limiting**: Built-in rate limiting prevents API abuse297- **Logging**: Sensitive information is not logged298299## 🤝 Contributing3003011. Fork the repository3022. Create a feature branch3033. Make your changes3044. Add tests if applicable3055. Run the test suite3066. Submit a pull request307308## 📄 License309310MIT License - see [LICENSE](LICENSE) file for details.311312## 📞 Support313314- **Issues**: [GitHub Issues](https://github.com/your-repo/lnbits-mcp-server/issues)315- **Documentation**: [GitHub Wiki](https://github.com/your-repo/lnbits-mcp-server/wiki)316- **LNbits**: [Official Documentation](https://lnbits.com/)317318## 📝 Changelog319320### v0.1.0321322- ✅ Initial release323- ✅ Core wallet operations (balance, details, payments)324- ✅ Payment processing (pay invoices, check status)325- ✅ Lightning address payments (pay user@domain.com addresses)326- ✅ Invoice creation and management327- ✅ Comprehensive error handling and structured logging328- ✅ Claude Desktop integration329- ✅ Type safety with Pydantic models330- ✅ Rate limiting and authentication support331332## 🎯 Quick Start3333341. **Install**: `pip install -e .`3352. **Add to Claude**: Update your `claude_desktop_config.json`3363. **Configure**: Use runtime configuration through your LLM client3374. **Test**: Ask Claude to check your wallet balance3385. **Enjoy**: Lightning-fast Bitcoin payments through AI! ⚡339340*For detailed setup instructions, see [QUICK_START.md](QUICK_START.md)*341342---343344*Built with ❤️ for the Bitcoin Lightning Network community*
Full transparency — inspect the skill content before installing.