金大哥 - breez-mcp MCP 详情

article

README

🚀 Breez MCP服务器 — FastMCP实现

Breez MCP服务器是一个统一的MCP服务器，它通过Breez SDK（Spark实现）使用FastMCP来公开Lightning功能。该服务器支持标准输入输出（stdio）和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 | ❌ | 8000 | HTTP服务器端口（仅HTTP模式） | | BREEZ_HTTP_PATH | ❌ | /mcp | HTTP端点路径（仅HTTP模式） |

🚀 运行服务器

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

STDIO模式（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

同时运行两种模式：

# STDIO模式
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 .

# STDIO模式（默认）
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保持标准输入输出连接，请在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", "/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语法从env块提供的环境中读取VAR的值。

从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聪的发票”之类的提示，以验证工具路由是否正常。

✨ 主要特性

可用工具

get_balance — 获取包含限额和格式化金额的全面钱包余额信息
get_node_info — 获取详细的节点信息，包括功能和同步状态
send_payment — 发送Lightning支付，并获取完整的交易详情
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协议。你需要向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中的绝对路径，并在更改配置后重启应用程序。

breez-mcp