LNbits-MCP-Server

LNbits MCP Server is an MCP (Model Context Protocol) server for LNbits, used to connect AI assistants to Lightning wallets. It is developed by the LNbits team, with the goal of allowing any MCP-compatible AI client to connect directly to your LNbits instance and perform wallet operations through natural language.

Purpose MCP is an open standard that allows AI assistants to use external tools. The role of this server is to let AI directly access your LNbits wallet, instead of copying and pasting API responses into a chat. You speak naturally, the AI calls the correct API endpoint, and the result is returned in the same conversation.

Main capabilities

• Wallet operations: check balance, view transaction history, get wallet details.
• Sending and receiving: pay Lightning invoices, pay Lightning addresses, create invoices.
• Extension support: LNURLp, TPoS, SatsPay, watch-only wallets.
• Admin tools: node information, user management, system statistics.
• Runtime configuration: configure the LNbits connection through chat, without an environment variable file.
• Security: API keys are stored only in memory and are never logged; HTTPS is recommended for production environments.
• Rate limiting: built-in request throttling to prevent accidental large numbers of API requests.

How to use The official steps take about two minutes and require Python 3.10+.

1. Install: run pip install -e . in the repository directory, and confirm that the lnbits-mcp-server command is available.
2. Add to the AI client: using Claude Desktop as an example, edit the configuration file. The macOS path is ~/Library/Application Support/Claude/claude_desktop_config.json, and the Windows path is %APPDATA%\Claude\claude_desktop_config.json. After saving, restart Claude Desktop; the server is activated only after the restart.
3. Connect LNbits: tell the AI your credentials directly in natural language, with no additional configuration file needed. Afterward, you can ask "What is my wallet balance?" to confirm whether it is available. API key location: open your LNbits instance and look under "Node URL, API keys and API docs" in the sidebar. Use the Admin key when you need to send payments, and use the Invoice key when you only need to check the balance and create invoices. You can converse naturally, and the AI will determine which tool to call on its own; you can also chain requests, for example "Create a 5000 sat invoice and display the QR code" or "Check whether the last payment succeeded, and if it did, what is my new balance?". When paying a Lightning address, you can directly say "Send 1000 sats to user@domain.com" without creating an invoice first.

Configuration reference Most users can just use runtime configuration. The environment variable approach is also supported, and at least one authentication method is required; in most scenarios, LNBITS_API_KEY together with api_key_header is sufficient. The server is usually started automatically by the AI client, but it can also be run manually for testing or debugging connection issues, or credentials can be set through environment variables, which is suitable for testing outside the AI client, running in Docker, or integrating into scripts.

Use cases Suitable for users who want to manage an LNbits Lightning wallet through natural language, including checking balances and transactions, creating and paying invoices, paying Lightning addresses, managing LNbits extensions, and performing node and user management when an admin key is available.

Limitations and notes

• Requires Python 3.10+, and pip install -e . must be run from the repository directory.
• After modifying the configuration file, the AI client must be restarted for the server to activate.
• The Invoice key can only create invoices and check the balance; sending payments requires the Admin key.
• Before sending a payment, confirm that the LNbits wallet balance is sufficient.
• When paying a Lightning address, the recipient's server must be reachable.
• Remote instances should use https://。
• Admin tools are available only when connected with a Super User or admin-level API key; extension tools appear only when the corresponding extension is installed on the LNbits instance.
• Runtime configuration only needs to be configured once per session, and the server remembers the settings until restart.

The project is open source, and contributions are welcome by forking the repository, creating a feature branch, making changes and adding tests, and submitting a pull request.