Breez MCP Server — 快速MCP实现

一个统一的MCP服务器，通过Breez SDK（Spark实现）使用FastMCP暴露Lightning功能。支持标准I/O和HTTP传输模式。

预备条件

• Python 3.11+（用于本地开发或uvx）
• Docker（可选，用于容器工作流）
• uv（可选，用于临时环境）
• 您可以通过这里请求Breez API密钥

配置凭证

cp .env.example .env

编辑.env文件并添加您的密钥。所需变量如下：

变量	必填	默认值	目的
BREEZ_API_KEY	✅	–	Breez Spark API密钥
BREEZ_MNEMONIC	✅	–	控制钱包的12字助记词
BREEZ_NETWORK	❌	mainnet	设置为testnet以供沙盒使用
BREEZ_DATA_DIR	❌	./data	钱包存储目录
BREEZ_TRANSPORT_MODE	❌	stdio	传输模式：stdio，http 或 asgi
BREEZ_HTTP_HOST	❌	0.0.0.0	HTTP服务器主机（仅限HTTP模式）
BREEZ_HTTP_PORT	❌	800_0	HTTP服务器端口（仅限HTTP模式）
BREEZ_HTTP_PATH	❌	/mcp	HTTP端点路径（仅限HTTP模式）

运行服务器

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

标准I/O模式（默认MCP客户端）

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

# 本地虚拟环境
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python -m src.main

# 或使用uvx（无持久虚拟环境）
uvx --from . breez-mcp

HTTP模式（用于Web API访问）

用于通过HTTP API访问MCP服务器：

# 设置环境变量
export BREEZ_TRANSPORT_MODE=http

# 或添加到.env文件
echo "BREEZ_TRANSPORT_MODE=http" >> .env

# 运行服务器
python -m src.main

服务器将在http://localhost:8000/mcp可用。

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

用于与Gunicorn等外部ASGI服务器部署：

# 设置环境变量
export BREEZ_TRANSPORT_MODE=asgi

# 使用uvicorn运行
uvicorn src.main:app --host 0.0.0.0 --port 8000

# 或使用Gunicorn（生产环境）
gunicorn src.main:app -w 4 -k uvicorn.workers.UvicornWorker

Docker Compose

同时运行两种模式：

# 标准I/O模式
docker compose --profile stdio up -d
docker compose logs -f breez-mcp-stdio

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

# 停止
docker compose --profile http down
docker compose --profile stdio down

Docker（直接）

# 构建镜像
docker build -t breez-mcp .

# 标准I/O模式（默认）
docker run --rm \
  -e BREEZ_API_KEY="$BREEZ_API_KEY" \
  -e BREEZ_MNEMONIC="$BREEZ_MNEMONIC" \
  -v $(pwd)/data:/app/data \
  breez-mcp

# HTTP模式
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连接，请在docker run命令中添加-i。

Claude Desktop集成

快速安装

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", "/绝对路径/to/breez-mcp/data:/app/data",
        "breez-mcp"
      ],
      "cwd": "/绝对路径/to/breez-mcp",
      "env": {
        "BREEZ_API_KEY": "${env:BREEZ_API_KEY}",
        "BREEZ_MNEMONIC": "${env:BREEZ_MNEMONIC}",
        "BREEZ_NETWORK": "mainnet"
      }
    }
  }
}

Docker的-e VAR语法从通过env块提供的环境中读取VAR的值。

从Claude Desktop使用uvx

{
  "mcpServers": {
    "breez": {
      "command": "uvx",
      "args": ["--from", ".", "breez-mcp"],
      "cwd": "/绝对路径/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 — 发送带有完整交易详情的Lightning支付
• create_invoice — 生成带有所有发票数据的BOLT11发票
• list_payments — 包含完整详情的综合支付历史

示例提示

• "检查我的钱包余额"
• "创建1000 sats的咖啡发票"
• "发送支付给lnbc1..."
• "显示我最近的支付"

HTTP API使用（HTTP模式）

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

健康检查

curl http://localhost:8000/health

列出可用工具

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

调用工具（MCP协议）

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

例如，使用MCP Inspector或其他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；将密钥保存在shell或密钥管理器中。
• 将助记词视为钱包的私钥。一旦泄露立即更换。
• 默认网络是mainnet。对于实验，请显式设置BREEZ_NETWORK=testnet。
• 使用容器时，挂载./data以在运行之间保存状态，并防止容器层中的密钥泄漏。

故障排除

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