Breez MCP

基於Breez SDK的閃電網絡MCP服務器，支持STDIO和HTTP傳輸模式，提供錢包餘額查詢、支付發送、發票創建等閃電網絡功能

金融人工智能聊天機器人 #閃電網絡 #錢包服務 #支付工具 .Python

評分 : 2.5分

下載量 : 4.1K

更新時間 : 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中的絕對路徑，並在更改配置後重啟應用程序。