Breez MCP Server — FastMCP Implementation

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:

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.