home / mcp / breez mcp server

Breez MCP Server

Breez MCP based on Breez SDK (Spark implementation) for easy use of Lightning with AI agents

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "breez-breez-mcp": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "BREEZ_API_KEY": "YOUR_API_KEY",
        "BREEZ_NETWORK": "testnet",
        "BREEZ_DATA_DIR": "./data",
        "BREEZ_MNEMONIC": "YOUR_MNEMONIC",
        "BREEZ_HTTP_HOST": "0.0.0.0",
        "BREEZ_HTTP_PATH": "/mcp",
        "BREEZ_HTTP_PORT": "8000",
        "BREEZ_TRANSPORT_MODE": "http"
      }
    }
  }
}

You run the Breez MCP Server to expose Lightning functionality through the Breez SDK using FastMCP. It supports both stdio and HTTP transports, letting you connect local MCP clients or web-based integrations to manage wallets, invoices, and payments with Lightning.

How to use

You can run the MCP server in stdio mode for local MCP clients or in HTTP mode to expose an HTTP API. In stdio mode, you interact with client tools directly on your machine. In HTTP mode, you call the server over HTTP at its configured host and port. Your credentials (API key and wallet mnemonic) are required to authenticate and access your Breez-enabled wallet.

How to install

# Prerequisites
Python 3.11+ (for local development or uvx)
Docker (optional, for container workflows)
uv (optional, for ephemeral environments)

# Prepare environment
cp .env.example .env

# Edit .env with your secrets. Required variables:
# BREEZ_API_KEY, BREEZ_MNEMONIC are required
# Optional: BREEZ_NETWORK (default mainnet), BREEZ_TRANSPORT_MODE (default stdio)

# Install dependencies and start in stdio mode (default for MCP clients)
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python -m src.main

# Or run with uvx (no persistent venv)
uvx --from . breez-mcp

# If you prefer HTTP mode, set transport and run
export BREEZ_TRANSPORT_MODE=http
python -m src.main

Additional configuration and start flows

Configure credentials and transport mode in your environment before starting. The following environment variables are used to control how the server connects to Breez and how it exposes its API.

Security and maintenance

- Never commit .env; keep secrets in your environment or a secrets manager. Rotate the mnemonic immediately if you suspect it has leaked. The default network is mainnet; set BREEZ_NETWORK to testnet for sandbox usage. When using containers, preserve state by mounting a data directory to avoid secret leakage and to keep wallet data intact between runs.

Troubleshooting

- Missing environment variables: ensure .env exists or export the required variables before starting. - SDK connection failures: verify required env vars and check the health endpoint at the configured HTTP host/port. - Claude Desktop or external tool cannot locate the server: confirm absolute paths in the configuration and restart after changes.

Tools and capabilities

The server provides a set of wallet and Lightning-related tools to manage your funds and invoices. These include querying balance, obtaining node information, sending payments, creating invoices, and listing payments.

Available tools

get_balance

Query the wallet balance with formatting and limits.

get_node_info

Retrieve detailed node information including capabilities and sync status.

send_payment

Send a Lightning payment with full transaction details.

create_invoice

Generate a BOLT11 invoice with associated data.

list_payments

List full payment history with detailed records.