Breez MCP

基于Breez SDK的闪电网络MCP服务器，支持STDIO和HTTP传输模式，提供钱包余额查询、支付发送、发票创建等闪电网络功能

金融人工智能聊天机器人 #闪电网络 #钱包服务 #支付工具 .Python

评分 : 2.5分

下载量 : 4.2K

更新时间 : 2025-11-12

打开站点

什么是Breez MCP Server?

Breez MCP Server是一个Model Context Protocol服务器，它将比特币闪电网络功能集成到AI助手（如Claude）中。通过这个服务器，AI助手可以帮您管理闪电网络钱包，包括查看余额、发送支付、创建发票等功能，无需您手动操作复杂的闪电网络技术。

如何使用Breez MCP Server?

使用Breez MCP Server需要三个简单步骤：1) 获取Breez API密钥和助记词；2) 配置环境变量；3) 将服务器连接到您的AI助手。一旦配置完成，您就可以通过自然语言与AI助手交互来管理您的闪电网络钱包。

适用场景

Breez MCP Server特别适合以下场景：日常小额支付管理、自动发票生成、支付历史查询、钱包余额监控，以及希望通过AI助手简化闪电网络操作的非技术用户。

主要功能

余额管理

全面查看钱包余额，包括可用余额、限额信息和格式化金额显示，让您随时了解资金状况

节点信息

获取详细的节点信息，包括节点能力、同步状态和网络连接状态

发送支付

安全发送闪电网络支付，提供完整的交易详情和支付状态跟踪

创建发票

生成标准的BOLT11发票，包含所有必要的发票数据和元信息

支付历史

查看全面的支付历史记录，包括发送和接收的完整交易详情

多传输模式

支持STDIO和HTTP两种传输模式，适应不同的使用场景和部署需求

优势

用户友好：通过自然语言与AI助手交互，无需学习复杂的技术命令

多平台支持：支持本地运行、Docker容器和云部署等多种运行方式

安全可靠：使用行业标准的API密钥和助记词进行身份验证

灵活部署：提供STDIO模式用于AI助手集成，HTTP模式用于Web API访问

完整功能：覆盖闪电网络钱包的核心操作需求

局限性

需要申请API密钥：使用前需要向Breez申请API访问权限

依赖外部服务：需要稳定的网络连接来访问Breez基础设施

技术门槛：初始配置需要一定的技术知识来设置环境变量

测试限制：测试网络可能需要单独的配置和资源

如何使用

获取API凭证

访问Breez官方网站申请API密钥，并准备好12个单词的助记词来控制您的钱包

配置环境变量

创建.env文件并设置必要的环境变量，包括API密钥、助记词和网络类型

选择运行模式

根据您的需求选择合适的运行模式：STDIO模式用于AI助手集成，HTTP模式用于API访问

集成到AI助手

配置您的AI助手（如Claude Desktop）连接到Breez MCP服务器

使用案例

日常余额查询

快速查看钱包当前余额和可用限额，了解资金状况

创建收款发票

为商品或服务创建收款发票，分享给付款方

发送支付

向商家或个人发送闪电网络支付

查看交易历史

回顾近期的支付记录，了解资金流向

常见问题

如何获取Breez API密钥？

STDIO模式和HTTP模式有什么区别？

我应该使用主网还是测试网？

如果我的助记词泄露了怎么办？

Claude Desktop无法连接到服务器怎么办？

如何验证服务器是否正常工作？

🚀 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中的绝对路径，并在更改配置后重启应用程序。