Breez MCP

🚀 Breez MCP Server — FastMCP実装

FastMCPを使用して、Breez SDK（Spark実装）を通じてLightning機能を公開する統一されたMCPサーバーです。stdioとHTTPの両方のトランスポートモードをサポートしています。

🚀 クイックスタート

このセクションでは、Breez MCP Serverを起動するための前提条件、クレデンシャルの設定、サーバーの実行方法について説明します。

前提条件

• Python 3.11以上（ローカル開発またはuvx用）
• Docker（オプション、コンテナワークフロー用）
• uv（オプション、一時的な環境用）
• Breez APIキー。こちらから申請できます。

クレデンシャルの設定

cp .env.example .env

.envファイルを開き、シークレット情報を編集してください。必要な変数は以下の通りです。

サーバーの実行

ワークフローに適したトランスポートモードとランタイムを選択してください。

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で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", "/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を実行して、サーバーが登録されていることを確認します。
• 「ウォレットの残高を確認」や「1000サットの請求書を作成」などのClaudeプロンプトを実行して、ツールのルーティングを検証します。

利用可能なツール

• 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ファイルをコミットしないでください。シークレット情報はシェルまたはシークレットマネージャーに保管してください。
• ニーモニックはウォレットの秘密鍵として扱います。漏洩した場合はすぐにローテーションしてください。
• デフォルトのネットワークはmainnetです。実験用には、明示的にBREEZ_NETWORK=testnetを設定してください。
• コンテナを使用する場合は、./dataをマウントして、実行間で状態を保持し、コンテナレイヤーでのシークレット漏洩を防いでください。

トラブルシューティング

• 環境変数が不足している場合 — .envファイルが存在することを確認するか、起動前に必要な変数をエクスポートしてください。
• SDK接続エラーの場合 — 必要な環境変数を確認し、python list_payments_cli.py --limit 1 --verboseを実行してSDK接続を確認し、HTTPモードではhttp://localhost:8000/healthを確認してください。
• Claude Desktopがサーバーを見つけられない場合 — cwdの絶対パスを再確認し、設定変更後にアプリケーションを再起動してください。