# LNbits MCP Server
[](./LICENSE)
[](https://github.com/lnbits/lnbits)
Give your AI assistant a Lightning wallet. The LNbits MCP Server connects any [MCP-compatible](https://modelcontextprotocol.io/) AI client to your [LNbits](https://lnbits.com/) instance - check balances, create invoices, send payments, and manage extensions, all through natural language.
### What is MCP?
[Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open standard that lets AI assistants use external tools. Instead of copy-pasting API responses into a chat, MCP gives your AI direct access to your LNbits wallet. You talk naturally, the AI calls the right API endpoint, and you see the result - all in one conversation.
### Features
- **Wallet operations** - check balances, view transaction history, get wallet details
- **Send and receive** - pay Lightning invoices, pay Lightning addresses, create invoices
- **Extension support** - LNURLp, TPoS, SatsPay, Watch-only wallets
- **Admin tools** - node info, user management, system stats
- **Runtime config** - configure your LNbits connection through chat, no env files needed
- **Secure** - API keys are stored in memory only, never logged; HTTPS recommended for production
- **Rate limited** - built-in request throttling to prevent accidental API floods
---
## Table of Contents
- [Quick Start](#quick-start)
- [What you can say](#what-you-can-say)
- [Available Tools](#available-tools)
- [Configuration Reference](#configuration-reference)
- [Running the Server Manually](#running-the-server-manually)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
- [Contributing](#contributing)
- [Powered by LNbits](#powered-by-lnbits)
---
## Quick Start
Three steps, takes about two minutes.
### 1. Install
```bash
git clone https://github.com/lnbits/LNbits-MCP-Server.git
cd LNbits-MCP-Server
pip install -e .
```
> You need Python 3.10+ installed. If you're unsure, run `python3 --version` first.
### 2. Add to your AI client
Tell your MCP client where the server lives. For **Claude Desktop**, edit the config file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"lnbits": {
"command": "lnbits-mcp-server"
}
}
}
```
> Restart Claude Desktop after saving. The server only activates after a restart.
### 3. Connect to your LNbits
Now just talk to your AI. No extra config files needed - tell it your credentials in plain language:
```
Configure lnbits.
URL: https://your-lnbits-instance.com
Key: your_api_key_here
Auth method: api_key_header
```
That's it. Try asking "What's my wallet balance?" to confirm it works.
> **Where's my API key?** Open your LNbits instance, look in the sidebar under "Node URL, API keys and API docs". Use the **Admin key** if you want to send payments, or the **Invoice key** if you only need to check balances and create invoices.
## What you can say
Just talk naturally. The AI figures out which tool to call.
```
"Check my wallet balance"
"Create an invoice for 1000 sats with memo 'Coffee payment'"
"Pay this invoice: lnbc10u1p3..."
"Send 500 sats to alice@lnbits.com"
"Show me my recent payments"
"Decode this invoice and tell me what it's for"
```
> You can also chain requests: "Create a 5000 sat invoice and show me the QR code" or "Check if that last payment went through, and if so, what's my new balance?"
## Available Tools
These are the tools the AI uses behind the scenes. You don't need to call them directly - just describe what you want and the AI picks the right one.
### Configuration
| Tool | Description |
|---|---|
| `configure_lnbits` | Set LNbits URL, API key, and auth method at runtime |
| `get_lnbits_configuration` | Show current connection settings |
| `test_lnbits_configuration` | Verify the connection works |
> You only need to configure once per session. The server remembers your settings until you restart it.
### Wallet
| Tool | Description |
|---|---|
| `get_wallet_details` | Wallet info including balance and keys |
| `get_wallet_balance` | Current balance |
| `get_payments` | Payment history |
| `check_connection` | Test connection to LNbits |
### Payments
| Tool | Description |
|---|---|
| `pay_invoice` | Pay a BOLT11 Lightning invoice |
| `pay_lightning_address` | Pay a Lightning address (user@domain.com) |
| `get_payment_status` | Check status by payment hash |
| `decode_invoice` | Decode and inspect a Lightning invoice |
| `create_invoice` | Create a new Lightning invoice |
> **Tip:** You can pay Lightning addresses directly - just say "Send 1000 sats to user@domain.com". No need to create an invoice first.
### Extensions (when enabled)
These tools appear when you have the corresponding extensions installed on your LNbits instance.
| Tool | Description |
|---|---|
| `create_lnurlp_link` / `get_lnurlp_links` | LNURLp pay links |
| `create_tpos` / `get_tpos_list` | TPoS terminals |
| `create_satspay_charge` / `get_satspay_charges` | SatsPay charges |
| `create_watchonly_wallet` / `get_watchonly_wallets` | Watch-only wallets |
### Admin (requires admin key)
Only available when you connect with a Super User or admin-level API key.
| Tool | Description |
|---|---|
| `get_node_info` | Lightning node information |
| `list_users` / `create_user` | User management |
| `get_system_stats` | System statistics |
## Configuration Reference
Most people just use the runtime config (step 3 above). But if you prefer environment variables, these work too:
| Variable | Description | Default |
|---|---|---|
| `LNBITS_URL` | LNbits instance URL | `https://demo.lnbits.com` |
| `LNBITS_API_KEY` | API key | - |
| `LNBITS_BEARER_TOKEN` | Bearer token (alternative auth) | - |
| `LNBITS_OAUTH2_TOKEN` | OAuth2 token (alternative auth) | - |
| `LNBITS_AUTH_METHOD` | `api_key_header`, `api_key_query`, `http_bearer`, or `oauth2` | `api_key_header` |
| `LNBITS_TIMEOUT` | Request timeout (seconds) | `30` |
| `LNBITS_MAX_RETRIES` | Max retries on failure | `3` |
| `LNBITS_RATE_LIMIT_PER_MINUTE` | Rate limit | `60` |
> At least one auth method is required. For most setups, `LNBITS_API_KEY` with `api_key_header` is all you need.
## Running the Server Manually
Your AI client usually starts the server automatically. But if you want to test it directly or debug connection issues, you can run it yourself:
```bash
# Using the installed command
lnbits-mcp-server
# Or run directly with Python
python -m lnbits_mcp_server.server
```
You can also set credentials via environment variables instead of runtime config:
```bash
export LNBITS_URL="https://your-lnbits-instance.com"
export LNBITS_API_KEY="your_api_key_here"
lnbits-mcp-server
```
> This is useful for testing outside an AI client, running in Docker, or integrating into scripts.
## Troubleshooting
**Server won't start**
- Check that Python 3.10+ is installed: `python3 --version`
- Make sure you ran `pip install -e .` from the repo directory
- Verify the `lnbits-mcp-server` command is available: `which lnbits-mcp-server`
**Connection fails after configuring**
- Verify your LNbits instance is running and reachable from your machine
- Double-check the API key - Admin and Invoice keys are different
- Make sure you're using `https://` for remote instances
**AI client doesn't show LNbits tools**
- Restart your AI client after editing the config file
- Check that the path in `claude_desktop_config.json` is correct
- Look at your client's logs for MCP connection errors
**Payments fail**
- Invoice key can only create invoices and check balances - use Admin key for sending payments
- Check that your LNbits wallet has sufficient balance
- For Lightning address payments, the recipient's server must be reachable
## Development
```bash
git clone https://github.com/lnbits/LNbits-MCP-Server.git
cd LNbits-MCP-Server
pip install -e .[dev]
# Run tests
pytest
# Format
black src tests
isort src tests
# Type check
mypy src
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes and add tests
4. Submit a pull request
Questions? Drop by the [Telegram group](https://t.me/lnbits) first - a quick chat often saves a round-trip on the PR.
## Powered by LNbits
[LNbits](https://lnbits.com) is a free and open-source Lightning accounts system.
[](https://docs.lnbits.com)
[](https://shop.lnbits.com/)
[](https://my.lnbits.com/login)
---
## Table of Contents
- [Quick Start](#quick-start)
- [What you can say](#what-you-can-say)
- [Available Tools](#available-tools)
- [Configuration Reference](#configuration-reference)
- [Running the Server Manually](#running-the-server-manually)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
- [Contributing](#contributing)
- [Powered by LNbits](#powered-by-lnbits)
---
## Quick Start
Three steps, takes about two minutes.
### 1. Install
```bash
git clone https://github.com/lnbits/LNbits-MCP-Server.git
cd LNbits-MCP-Server
pip install -e .
```
> You need Python 3.10+ installed. If you're unsure, run `python3 --version` first.
### 2. Add to your AI client
Tell your MCP client where the server lives. For **Claude Desktop**, edit the config file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"lnbits": {
"command": "lnbits-mcp-server"
}
}
}
```
> Restart Claude Desktop after saving. The server only activates after a restart.
### 3. Connect to your LNbits
Now just talk to your AI. No extra config files needed - tell it your credentials in plain language:
```
Configure lnbits.
URL: https://your-lnbits-instance.com
Key: your_api_key_here
Auth method: api_key_header
```
That's it. Try asking "What's my wallet balance?" to confirm it works.
> **Where's my API key?** Open your LNbits instance, look in the sidebar under "Node URL, API keys and API docs". Use the **Admin key** if you want to send payments, or the **Invoice key** if you only need to check balances and create invoices.
## What you can say
Just talk naturally. The AI figures out which tool to call.
```
"Check my wallet balance"
"Create an invoice for 1000 sats with memo 'Coffee payment'"
"Pay this invoice: lnbc10u1p3..."
"Send 500 sats to alice@lnbits.com"
"Show me my recent payments"
"Decode this invoice and tell me what it's for"
```
> You can also chain requests: "Create a 5000 sat invoice and show me the QR code" or "Check if that last payment went through, and if so, what's my new balance?"
## Available Tools
These are the tools the AI uses behind the scenes. You don't need to call them directly - just describe what you want and the AI picks the right one.
### Configuration
| Tool | Description |
|---|---|
| `configure_lnbits` | Set LNbits URL, API key, and auth method at runtime |
| `get_lnbits_configuration` | Show current connection settings |
| `test_lnbits_configuration` | Verify the connection works |
> You only need to configure once per session. The server remembers your settings until you restart it.
### Wallet
| Tool | Description |
|---|---|
| `get_wallet_details` | Wallet info including balance and keys |
| `get_wallet_balance` | Current balance |
| `get_payments` | Payment history |
| `check_connection` | Test connection to LNbits |
### Payments
| Tool | Description |
|---|---|
| `pay_invoice` | Pay a BOLT11 Lightning invoice |
| `pay_lightning_address` | Pay a Lightning address (user@domain.com) |
| `get_payment_status` | Check status by payment hash |
| `decode_invoice` | Decode and inspect a Lightning invoice |
| `create_invoice` | Create a new Lightning invoice |
> **Tip:** You can pay Lightning addresses directly - just say "Send 1000 sats to user@domain.com". No need to create an invoice first.
### Extensions (when enabled)
These tools appear when you have the corresponding extensions installed on your LNbits instance.
| Tool | Description |
|---|---|
| `create_lnurlp_link` / `get_lnurlp_links` | LNURLp pay links |
| `create_tpos` / `get_tpos_list` | TPoS terminals |
| `create_satspay_charge` / `get_satspay_charges` | SatsPay charges |
| `create_watchonly_wallet` / `get_watchonly_wallets` | Watch-only wallets |
### Admin (requires admin key)
Only available when you connect with a Super User or admin-level API key.
| Tool | Description |
|---|---|
| `get_node_info` | Lightning node information |
| `list_users` / `create_user` | User management |
| `get_system_stats` | System statistics |
## Configuration Reference
Most people just use the runtime config (step 3 above). But if you prefer environment variables, these work too:
| Variable | Description | Default |
|---|---|---|
| `LNBITS_URL` | LNbits instance URL | `https://demo.lnbits.com` |
| `LNBITS_API_KEY` | API key | - |
| `LNBITS_BEARER_TOKEN` | Bearer token (alternative auth) | - |
| `LNBITS_OAUTH2_TOKEN` | OAuth2 token (alternative auth) | - |
| `LNBITS_AUTH_METHOD` | `api_key_header`, `api_key_query`, `http_bearer`, or `oauth2` | `api_key_header` |
| `LNBITS_TIMEOUT` | Request timeout (seconds) | `30` |
| `LNBITS_MAX_RETRIES` | Max retries on failure | `3` |
| `LNBITS_RATE_LIMIT_PER_MINUTE` | Rate limit | `60` |
> At least one auth method is required. For most setups, `LNBITS_API_KEY` with `api_key_header` is all you need.
## Running the Server Manually
Your AI client usually starts the server automatically. But if you want to test it directly or debug connection issues, you can run it yourself:
```bash
# Using the installed command
lnbits-mcp-server
# Or run directly with Python
python -m lnbits_mcp_server.server
```
You can also set credentials via environment variables instead of runtime config:
```bash
export LNBITS_URL="https://your-lnbits-instance.com"
export LNBITS_API_KEY="your_api_key_here"
lnbits-mcp-server
```
> This is useful for testing outside an AI client, running in Docker, or integrating into scripts.
## Troubleshooting
**Server won't start**
- Check that Python 3.10+ is installed: `python3 --version`
- Make sure you ran `pip install -e .` from the repo directory
- Verify the `lnbits-mcp-server` command is available: `which lnbits-mcp-server`
**Connection fails after configuring**
- Verify your LNbits instance is running and reachable from your machine
- Double-check the API key - Admin and Invoice keys are different
- Make sure you're using `https://` for remote instances
**AI client doesn't show LNbits tools**
- Restart your AI client after editing the config file
- Check that the path in `claude_desktop_config.json` is correct
- Look at your client's logs for MCP connection errors
**Payments fail**
- Invoice key can only create invoices and check balances - use Admin key for sending payments
- Check that your LNbits wallet has sufficient balance
- For Lightning address payments, the recipient's server must be reachable
## Development
```bash
git clone https://github.com/lnbits/LNbits-MCP-Server.git
cd LNbits-MCP-Server
pip install -e .[dev]
# Run tests
pytest
# Format
black src tests
isort src tests
# Type check
mypy src
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes and add tests
4. Submit a pull request
Questions? Drop by the [Telegram group](https://t.me/lnbits) first - a quick chat often saves a round-trip on the PR.
## Powered by LNbits
[LNbits](https://lnbits.com) is a free and open-source Lightning accounts system.
[](https://docs.lnbits.com)
[](https://shop.lnbits.com/)
[](https://my.lnbits.com/login)