Breez MCP Server

Breez MCP服务器——FastMCP实现

一个统一的MCP服务器，通过Breez SDK（Spark实现）使用FastMCP公开Lightning功能。支持stdio和HTTP传输模式。

先决条件

• Python 3.11+（用于本地开发或 uvx)
• 码头工人 （可选，用于容器工作流）
• 紫外线 （可选，适用于短暂环境）
• 您可以请求的Breez API密钥 这里

配置凭据

cp .env.example .env

编辑 .env 和你的秘密。所需变量：

运行服务器

选择适合您工作流程的传输模式的运行时。

STDIO模式（MCP客户端的默认模式）

用于Claude Desktop和其他MCP客户端：

# 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模式（用于web API访问）

通过HTTP API访问MCP服务器：

# 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

服务器将在以下时间可用 http://localhost:8000/mcp

ASGI模式（适用于外部ASGI服务器）

对于像Gunicorn这样的外部ASGI服务器的部署：

# 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

同时运行两种模式：

# 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（直接）

# 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

要保持Claude Desktop的STDIN/STDOUT连接，请添加 -i 到 docker run 命令。

Claude桌面集成

快速安装

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

使用 -f .env 或 -v KEY=value 如果需要，在安装过程中提供凭据。

来自Claude Desktop的Docker

确保映像存在(docker build -t breez-mcp .)，然后配置：

{
  "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的 -e VAR 语法读取以下值 VAR 通过提供的环境 env 块。

来自Claude Desktop的uvx

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

验证

• 添加配置后重新启动Claude Desktop。
• 跑 mcp list 以确保服务器已注册。
• 询问Claude“检查我的钱包余额”或“创建1000 sats的发票”等提示，以验证工具路由。

可用工具

• get_balance --具有限额和格式化金额的综合钱包余额
• get_node_info --详细的节点信息，包括功能和同步状态
• send_payment --发送带有完整交易详细信息的闪电支付
• create_invoice --生成包含所有发票数据的BOLT11发票
• list_payments --全面的付款历史记录，包括全部详细信息

示例提示

• “检查我的钱包余额”
• “为1000包咖啡开具发票”
• “向lnbc1发送付款…”
• “显示我最近的付款”

HTTP API使用情况（HTTP模式）

在HTTP模式下运行时，您可以通过HTTP请求与MCP服务器交互：

健康检查

curl http://localhost:8000/health

列出可用工具

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

调用工具（MCP协议）

HTTP模式遵循HTTP上的MCP协议。您需要将格式正确的MCP JSON-RPC请求发送到 http://localhost:8000/mcp.

使用MCP检查器或其他MCP客户端的示例：

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

发送至：

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}'

安全说明

• 永不承诺 .env把秘密藏在你的壳里或秘密管理器里。
• 将助记词视为钱包的私钥。如果泄漏，请立即旋转。
• 默认网络为 mainnet。对于实验，请明确设置 BREEZ_NETWORK=testnet.
• 使用容器时，安装 ./data 以保持运行之间的状态并防止容器层中的秘密泄漏。

故障排除

• 缺少环境变量 --确保 .env 在开始之前，存在或导出所需的变量。
• SDK连接失败 --验证所需的环境变量，尝试 python list_payments_cli.py --limit 1 --verbose 确认SDK连接，并检查 http://localhost:8000/health 在HTTP模式下。
• Claude Desktop找不到服务器 --仔细检查绝对路径 cwd 并在配置更改后重新启动应用程序。