LNbits MCP Server

Give your AI assistant a Lightning wallet. The LNbits MCP Server connects any MCP-compatible AI client to your LNbits instance - check balances, create invoices, send payments, and manage extensions, all through natural language.

What is MCP?

Model Context Protocol (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
• What you can say
• Available Tools
• Configuration Reference
• Running the Server Manually
• Troubleshooting
• Development
• Contributing
• Powered by LNbits

Quick Start

Three steps, takes about two minutes.

1. Install

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

{
  "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

You only need to configure once per session. The server remembers your settings until you restart it.

Wallet

Payments

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.

Admin (requires admin key)

Only available when you connect with a Super User or admin-level API key.

Configuration Reference

Most people just use the runtime config (step 3 above). But if you prefer environment variables, these work too:

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:

# 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:

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

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 first - a quick chat often saves a round-trip on the PR.

Powered by LNbits

LNbits is a free and open-source Lightning accounts system.