Breez Lightning

A unified MCP server that exposes Lightning functionality through the Breez SDK (Spark implementation) using FastMCP. Supports both stdio and HTTP transport modes.

Prerequisites

• Python 3.11+ (for local development or uvx)
• Docker (optional, for container workflows)
• uv (optional, for ephemeral environments)
• Breez API key which you can request here

Configure Credentials

cp .env.example .env

Edit .env with your secrets. Required variables:

Variable	Required	Default	Purpose
BREEZ_API_KEY	✅	–	Breez Spark API key
BREEZ_MNEMONIC	✅	–	12-word mnemonic controlling the wallet
BREEZ_NETWORK	❌	mainnet	Set to testnet for sandbox usage
BREEZ_DATA_DIR	❌	./data	Wallet storage directory
BREEZ_TRANSPORT_MODE	❌	stdio	Transport mode: stdio, http, or asgi
BREEZ_HTTP_HOST	❌	0.0.0.0	HTTP server host (HTTP mode only)
BREEZ_HTTP_PORT	❌	8000	HTTP server port (HTTP mode only)
BREEZ_HTTP_PATH	❌	/mcp	HTTP endpoint path (HTTP mode only)

Run the Server

Choose the runtime that transport mode that fits your workflow.

STDIO Mode (Default for MCP clients)

For use with Claude Desktop and other MCP clients:

# Local virtualenv
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python -m src.main

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

HTTP Mode (for web API access)

For accessing the MCP server via HTTP API:

# Set environment variable
export BREEZ_TRANSPORT_MODE=http

# Or add to .env file
echo "BREEZ_TRANSPORT_MODE=http" >> .env

# Run the server
python -m src.main

The server will be available at http://localhost:8000/mcp

ASGI Mode (for external ASGI servers)

For deployment with external ASGI servers like Gunicorn:

# Set environment variable
export BREEZ_TRANSPORT_MODE=asgi

# Run with uvicorn
uvicorn src.main:app --host 0.0.0.0 --port 8000

# Or with Gunicorn (production)
gunicorn src.main:app -w 4 -k uvicorn.workers.UvicornWorker

Docker Compose

Run both modes simultaneously:

# STDIO mode
docker compose --profile stdio up -d
docker compose logs -f breez-mcp-stdio

# HTTP mode
docker compose --profile http up -d
docker compose logs -f breez-mcp-http

# Stop
docker compose --profile http down
docker compose --profile stdio down

Docker (direct)

# Build image
docker build -t breez-mcp .

# STDIO mode (default)
docker run --rm \
  -e BREEZ_API_KEY="$BREEZ_API_KEY" \
  -e BREEZ_MNEMONIC="$BREEZ_MNEMONIC" \
  -v $(pwd)/data:/app/data \
  breez-mcp

# HTTP mode
docker run --rm -p 8000:8000 \
  -e BREEZ_TRANSPORT_MODE=http \
  -e BREEZ_API_KEY="$BREEZ_API_KEY" \
  -e BREEZ_MNEMONIC="$BREEZ_MNEMONIC" \
  -v $(pwd)/data:/app/data \
  breez-mcp

To keep STDIN/STDOUT attached for Claude Desktop, add -i to the docker run command.

Claude Desktop Integration

Quick install

mcp install src.main --name "breez-mcp"

Use -f .env or -v KEY=value to supply credentials during installation if desired.

Docker from Claude Desktop

Ensure the image exists (docker build -t breez-mcp .), then configure:

{
  "mcpServers": {
    "breez": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "BREEZ_API_KEY",
        "-e", "BREEZ_MNEMONIC",
        "-e", "BREEZ_TRANSPORT_MODE=stdio",
        "-v", "/absolute/path/to/breez-mcp/data:/app/data",
        "breez-mcp"
      ],
      "cwd": "/absolute/path/to/breez-mcp",
      "env": {
        "BREEZ_API_KEY": "${env:BREEZ_API_KEY}",
        "BREEZ_MNEMONIC": "${env:BREEZ_MNEMONIC}",
        "BREEZ_NETWORK": "mainnet"
      }
    }
  }
}

Docker's -e VAR syntax reads the value of VAR from the environment supplied via the env block.

uvx from Claude Desktop

{
  "mcpServers": {
    "breez": {
      "command": "uvx",
      "args": ["--from", ".", "breez-mcp"],
      "cwd": "/absolute/path/to/breez-mcp",
      "env": {
        "BREEZ_API_KEY": "${env:BREEZ_API_KEY}",
        "BREEZ_MNEMONIC": "${env:BREEZ_MNEMONIC}",
      }
    }
  }
}

Verification

• Restart Claude Desktop after adding the configuration.
• Run mcp list to ensure the server registered.
• Ask Claude prompts like “Check my wallet balance” or “Create an invoice for 1000 sats” to validate tool routing.

Available Tools

• get_balance — comprehensive wallet balance with limits and formatted amounts
• get_node_info — detailed node information including capabilities and sync status
• send_payment — send a Lightning payment with complete transaction details
• create_invoice — generate a BOLT11 invoice with all invoice data
• list_payments — comprehensive payment history with full details

Example Prompts

• "Check my wallet balance"
• "Create an invoice for 1000 sats for coffee"
• "Send payment to lnbc1…"
• "Show me my recent payments"

HTTP API Usage (HTTP Mode)

When running in HTTP mode, you can interact with the MCP server via HTTP requests:

Health Check

curl http://localhost:8000/health

List Available Tools

curl http://localhost:8000/mcp/tools/list

Call a Tool (MCP Protocol)

The HTTP mode follows the MCP protocol over HTTP. You'll need to send properly formatted MCP JSON-RPC requests to http://localhost:8000/mcp.

Example using MCP Inspector or other MCP clients:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_balance",
    "arguments": {}
  },
  "id": 1
}

Send to:

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_balance","arguments":{}},"id":1}'

Security Notes

• Never commit .env; keep secrets in your shell or a secrets manager.
• Treat the mnemonic as the wallet’s private key. Rotate immediately if leaked.
• Default network is mainnet. For experimentation, explicitly set BREEZ_NETWORK=testnet.
• When using containers, mount ./data to preserve state between runs and prevent secret leakage in container layers.

Troubleshooting

• Missing environment variables — ensure .env exists or export the required variables before starting.
• SDK connection failures — verify required env vars, try python list_payments_cli.py --limit 1 --verbose to confirm SDK connectivity, and check http://localhost:8000/health in HTTP mode.
• Claude Desktop cannot find the server — double-check absolute paths in cwd and restart the application after configuration changes.