Btcpayserver MCP

🚀 BTCPayServer Model Context Protocol Server (Beta)

BTCPayServerとの統合を目的とした包括的なモデルコンテキストプロトコル（MCP）サーバーです。支払い処理、ストア管理、ユーザー管理、ウェブフック処理などのツールを提供し、完全なAPIカバレッジを備えています。

🚀 クイックスタート

BTCPayServer MCP Serverを使用することで、BTCPayServer APIとのやり取りが簡素化されます。以下のセクションでは、ツールの参照、AIアシスタントとの統合、サービスカタログ、使用パターン、インストール、設定、使用方法、開発、セキュリティに関する考慮事項、BTCPayServerとの互換性、コントリビュート方法、ライセンス、サポートについて説明します。

✨ 主な機能

• APIツールの提供：BTCPayServer APIとのやり取りに必要なツールを提供します。
• AIアシスタントとの統合：Claude DesktopなどのAIアシスタントとの統合が可能です。
• サービスカタログの充実：BTCPayServerの完全なAPIエコシステムにアクセスできます。
• エラーハンドリングの充実：包括的なエラーハンドリング機能を備えています。

📦 インストール

1. このリポジトリをクローンします：

git clone <repository-url>
cd btcpayserver-mcp

2. 依存関係をインストールします：

npm install

3. プロジェクトをビルドします：

npm run build

💻 使用例

基本的な使用法

BTCPayServer APIとのやり取りには、以下の3つのステップが必要です：

1. 探索：get_service_infoを使用して利用可能なメソッドを探索します。

get_service_info(serviceName: "invoices")

2. 理解：get_method_infoを使用してパラメータの要件を学習します。

get_method_info(serviceName: "invoices", methodName: "create")

3. 実行：btcpay_requestを使用して操作を実行します。

btcpay_request(serviceName: "invoices", methodName: "create", parameters: {storeId: "your-store-id", amount: "10.00", currency: "USD"})

高度な使用法

開発やデバッグには、以下のコマンドを使用できます。

MCPインスペクターを使用する場合： MCPインスペクターは、テスト用の視覚的なインターフェースを提供します。

# プロジェクトをビルドする
npm run build

# BTCPayServer MCP Serverとともにインスペクターを起動する
npx @modelcontextprotocol/inspector node dist/index.js

開発ワークフロー：

1. リポジトリをクローンする
2. 依存関係をインストールする：npm install
3. 開発モードを開始する：npm run build
4. サーバーを起動する：node dist/index.js
5. MCPインスペクターを使用して変更をテストする

📚 ドキュメント

ツール参照

BTCPayServer MCP Serverは、BTCPayServer APIとのやり取りに必要な一連のツールを提供します。

AIアシスタントとの統合

Claude Desktopとの統合

Claude Desktopとの統合には、claude_desktop_config.jsonに以下の設定を追加します。

{
  "mcpServers": {
    "btcpayserver-mcp": {
      "command": "node",
      "args": ["path/to/btcpayserver-mcp/dist/index.js"],
      "env": {
        "BTCPAY_BASE_URL": "https://your-btcpay-instance.com",
        "BTCPAY_API_KEY": "your_api_key_here",
        "BTCPAY_STORE_ID": "your_default_store_id"
      }
    }
  }
}

サービスカタログ

BTCPayServer MCPは、BTCPayServerの完全なAPIエコシステムにアクセスできます。各サービスの詳細情報については、BTCPayServer API Documentationを参照してください。

支払いサービス

ストア管理

ユーザーとアクセス管理

統合と自動化

システム

設定

MCPサーバーには、以下の環境変数が必要です。

• BTCPAY_BASE_URL - あなたのBTCPayServerインスタンスのURL（例：https://btcpay.example.com）
• BTCPAY_API_KEY - あなたのBTCPayServer APIキー
• BTCPAY_STORE_ID - （オプション）操作のデフォルトストアID

BTCPayServer APIキーの設定

1. あなたのBTCPayServerインスタンスにログインします。
2. アカウント → アカウントの管理 → APIキーに移動します。
3. キーの生成をクリックします。
4. あなたのユースケースに必要な権限を選択します：
   • ストア管理：btcpay.store.canmodifystoresettings
   • 支払いリクエスト：btcpay.store.cancreateinvoice
   • ユーザー管理：btcpay.user.canmodifyprofile
   • ウェブフック：btcpay.store.webhooks.canmodifywebhooks
   • など
5. 生成されたAPIキーをコピーします。

環境設定

プロジェクトのルートに.envファイルを作成します。

BTCPAY_BASE_URL=https://your-btcpay-instance.com
BTCPAY_API_KEY=your_api_key_here
BTCPAY_STORE_ID=your_default_store_id

または、直接環境変数を設定することもできます。

export BTCPAY_BASE_URL=https://your-btcpay-instance.com
export BTCPAY_API_KEY=your_api_key_here
export BTCPAY_STORE_ID=your_default_store_id

使用方法

MCPサーバーの実行

npm start

開発用には、以下のコマンドを使用します。

npm run dev

開発とデバッグ

MCPサーバーは、包括的なエラーハンドリング機能を備えています。

• 設定エラー：環境変数が不足している場合
• APIエラー：BTCPayServer APIとの通信に問題がある場合
• 検証エラー：入力パラメータが無効な場合
• 認証エラー：APIキーが無効または期限切れの場合

すべてのエラーは適切にフォーマットされ、説明的なメッセージとともに返されます。

🔧 技術詳細

プロジェクト構造

src/
├── index.ts              # 主なMCPサーバーの実装
├── services/             # BTCPayServerサービスの実装
│   ├── base-service.ts   # 基本サービスクラス
│   ├── invoices.ts       # 請求書管理
│   ├── payment-requests.ts # 支払いリクエストの処理
│   ├── stores.ts         # ストア管理
│   ├── webhooks.ts       # ウェブフック管理
│   └── ...               # その他のサービスモジュール
├── utils/
│   └── btcpay-client.ts  # BTCPayServer APIクライアント
└── types.ts              # TypeScriptの型定義

ビルド

npm run build

開発時の実行

npm run dev

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

セキュリティに関する考慮事項

1. APIキーのセキュリティ：APIキーをバージョン管理にコミットしないでください。
2. 環境変数：安全な環境変数管理を使用してください。
3. ウェブフックシークレット：常にウェブフックシークレットを使用して検証してください。
4. HTTPS：BTCPayServerインスタンスがHTTPSを使用していることを確認してください。
5. 権限：APIキーの権限には最小権限の原則を使用してください。

BTCPayServerとの互換性

このMCPサーバーは、BTCPayServer v1.7.0以降と互換性があります。公式のBTCPayServer REST API v1を使用しています。

コントリビュート方法

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 変更をコミットします。
4. ブランチにプッシュします。
5. プルリクエストを作成します。

サポート

問題や質問については、以下の方法で対応します。

1. BTCPayServerのドキュメントを確認します。
2. APIリファレンスを確認します。
3. このリポジトリにイシューを作成します。

このMCPを改善するために協力してください

注意：一部のメソッドが正常に動作しない場合があります。要件を報告し、プルリクエストを作成することで改善に協力してください。また、最新のAPIバージョンに追従するために、継続的な更新が必要です。