Bitnovo Pay

公式

Bitnovo Pay APIを通じてAIエージェントに暗号通貨支払い機能を提供するMCPサーバー。支払い作成、ステータス確認、QRコード生成、Webhook管理に対応し、複数のトンネルプロバイダー（ngrok、zrok、手動）をサポートします。

GitHub

Bitnovo Pay MCPで何ができますか？

オンチェーン暗号支払いを作成 — アシスタントに、create_payment_onchain を使用して特定のコインとユーロ金額の暗号通貨アドレスを生成するよう依頼します。
共有可能な支払いリンクを作成 — アシスタントに、create_payment_link を使用して顧客が暗号通貨を選択できるウェブ支払いURLを構築させます。
支払いステータスを確認 — get_payment_status を使用して、その識別子を用いて任意の支払いの現在の状態と詳細をリクエストします。
対応通貨を一覧表示 — list_currencies_catalog を使用して、オプションで最低ユーロ金額でフィルタリングされた利用可能な暗号通貨を取得します。
ブランド化された支払いQRを生成 — generate_payment_qr を使用して、既存の支払い用の高解像度QRコードを生成します。
ウェブフックイベントを検査 — get_webhook_events を使用して、Bitnovoから受信したリアルタイムの支払い通知を照会します。

ドキュメント

MCP Bitnovo Pay

AIエージェント向けBitnovo Pay統合のためのMCPサーバー

AIエージェントにBitnovo Pay API統合を通じて暗号通貨支払い機能を提供するModel Context Protocol (MCP) サーバーです。このサーバーにより、AIモデルは支払いの作成、支払いステータスの確認、QRコードの管理、暗号通貨カタログへのアクセスが可能になります。

🚀 機能

包括的な支払い管理のための8つのMCPツール:
- create_payment_onchain - 直接支払い用の暗号通貨アドレスを生成
- create_payment_link - リダイレクト処理付きのWeb支払いURLを作成
- get_payment_status - 詳細情報付きで支払いステータスを照会
- list_currencies_catalog - フィルタリング機能付きでサポートされている暗号通貨を取得
- generate_payment_qr - 既存の支払いからカスタムQRコードを生成
- get_webhook_events - リアルタイムで受信したWebhookイベントを照会
- get_webhook_url - 設定手順付きで公開Webhook URLを取得
- get_tunnel_status - トンネル接続ステータスを診断
3つのトンネルプロバイダーを備えた自動Webhookシステム:
- 🔗 ngrok: 無料の永続URL（アカウントごとに1つの静的ドメイン）
- 🌐 zrok: 永続URL付きの100%無料のオープンソース
- 🏢 manual: パブリックIPを持つサーバー向け（N8N、Opal、VPS）
マルチLLMサポート - 以下と互換性があります:
- 🤖 OpenAI ChatGPT (GPT-5、GPT-4o、Responses API、Agents SDK)
- 🧠 Google Gemini (Gemini 2.5 Flash/Pro Sept 2025、CLI、FastMCP)
- 🔮 Claude (Claude Desktop、Claude Code)
高品質QRコード (v1.1.0以降):
- 📱 最新のディスプレイ向けにデフォルト512px解像度（300pxから向上）
- 🖨️ プロフェッショナルな印刷向けに最大2000pxをサポート
- ✨ 最適化された補間アルゴリズムによるシャープなエッジ
- 🎨 スムーズなロゴスケーリングを備えたカスタムBitnovo Payブランディング
デフォルトでプライバシー保護 - ログで機密データをマスクし、データ露出を最小限に
セキュア - HTTPS強制、HMAC署名検証、安全なシークレット処理
信頼性 - 組み込みのリトライロジック、タイムアウト処理、ステートレス動作

📋 前提条件

Node.js 18以上
Bitnovo Payアカウント（デバイスIDとオプションのデバイスシークレット付き）
環境設定（以下のセットアップガイドを参照）

⚡ クイックスタート

1. Bitnovo認証情報を取得する

Bitnovo Payでサインアップ
BitnovoダッシュボードからデバイスIDを取得
（オプション）Webhook署名検証用のデバイスシークレットを生成

2. MCPクライアントを設定する

この設定をMCPクライアント設定ファイルに追加します:

Claude Desktopの場合 (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

OpenAI ChatGPTの場合 (OpenAIセットアップガイドを参照):

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

3. MCPクライアントを再起動する

Claude Desktop、ChatGPT、またはMCPクライアントを再起動してサーバーをロードします。

4. 統合をテストする

AIアシスタントに次のように依頼します: 「10ユーロの支払いを作成して」

☁️ クラウドデプロイメント (v1.2.0で新登場)

MCP Bitnovo Payは、HTTPトランスポートモードでのクラウドプラットフォームへのリモートデプロイメントをサポートするようになりました。これにより、claude.aiなどのAIプラットフォームがMCPサーバーにリモート接続できます。

Railwayにデプロイ (推奨)

クイックセットアップ:

「Deploy to Railway」をクリックするか、新しいプロジェクトを作成
環境変数を設定:
- BITNOVO_DEVICE_ID - BitnovoデバイスID
- BITNOVO_BASE_URL - https://pos.bitnovo.com
デプロイ（RailwayがDockerfileを自動検出）
公開URLを取得: https://your-app.up.railway.app

claude.aiへの接続:

設定 → Model Context Protocolでサーバーを追加
サーバーURL: https://your-app.up.railway.app/mcp

📖 完全ガイド: 詳細なデプロイ手順、トラブルシューティング、設定についてはRAILWAY.mdを参照してください。

Dockerにデプロイ

# Build the image
docker build -t mcp-bitnovo-pay .

# Run with environment variables
docker run -d \
  -p 3000:3000 \
  -e PORT=3000 \
  -e BITNOVO_DEVICE_ID=your_device_id \
  -e BITNOVO_BASE_URL=https://pos.bitnovo.com \
  mcp-bitnovo-pay

その他のプラットフォームにデプロイ

このサーバーは、Node.jsとDockerをサポートする任意のプラットフォームで動作します:

Heroku: 環境変数付きでDockerfileをプッシュ
Fly.io: fly.toml設定でデプロイ
Google Cloud Run: Dockerコンテナをデプロイ
AWS ECS/Fargate: タスク定義でデプロイ

必要な環境変数:

PORT - HTTPポート（ほとんどのプラットフォームで自動設定）
BITNOVO_DEVICE_ID - BitnovoデバイスID
BITNOVO_BASE_URL - Bitnovo API URL

トランスポートモード検出:

PORT環境変数が設定されている場合 → HTTPモード（リモート接続）
PORTがない場合 → stdioモード（ローカル接続）

📦 インストールオプション

オプションA: npxを使用 (推奨)

インストール不要！ npxコマンドが自動的に最新バージョンをダウンロードして実行します。

npx -y @bitnovopay/mcp-bitnovo-pay

利点:

✅ 常に最新バージョンを取得
✅ 手動更新不要
✅ ローカルインストール不要
✅ すぐに動作

オプションB: リポジトリをクローン (開発用)

コードを変更する必要がある貢献者や上級ユーザー向け:

# Clone the repository
git clone https://github.com/bitnovo/mcp-bitnovo-pay.git
cd mcp-bitnovo-pay

# Or install from npm
npm install -g @bitnovopay/mcp-bitnovo-pay

# Install dependencies
npm install

# Build the project
npm run build

# Run locally
npm start

利点:

✅ ソースコードを完全に制御
✅ 変更とテストが可能
✅ プロジェクトへの貢献に最適

🔧 LLMプラットフォーム別設定

AIプラットフォームを選択し、特定のセットアップガイドに従ってください:

Claude Desktop (Anthropic)

設定ファイルの場所: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ガイド: Claudeセットアップガイド

基本設定:

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

Webhookを使用する場合 (リアルタイム支払い通知用):

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com",
        "BITNOVO_DEVICE_SECRET": "your_device_secret_hex",
        "WEBHOOK_ENABLED": "true",
        "TUNNEL_ENABLED": "true",
        "TUNNEL_PROVIDER": "ngrok",
        "NGROK_AUTHTOKEN": "your_ngrok_token",
        "NGROK_DOMAIN": "your-domain.ngrok-free.app"
      }
    }
  }
}

OpenAI ChatGPT

ガイド: OpenAIセットアップガイド サポート対象: GPT-5、GPT-4o、Responses API、Agents SDK

基本設定:

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

Google Gemini

ガイド: Geminiセットアップガイド サポート対象: Gemini 2.5 Flash/Pro (2025年9月)、CLI、FastMCP

基本設定:

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

環境変数

変数	必須	説明	例
`BITNOVO_DEVICE_ID`	✅ はい	Bitnovo Payデバイス識別子	`12345678-abcd-1234-abcd-1234567890ab`
`BITNOVO_BASE_URL`	✅ はい	Bitnovo APIエンドポイント	`https://pos.bitnovo.com` (本番) `https://payments.pre-bnvo.com` (開発)
`BITNOVO_DEVICE_SECRET`	⚠️ オプション	Webhook検証用のHMACシークレット	`your_hex_secret`
`WEBHOOK_ENABLED`	⚠️ オプション	Webhookサーバーを有効化	`true` または `false`
`TUNNEL_ENABLED`	⚠️ オプション	Webhook用トンネルを自動起動	`true` または `false`
`TUNNEL_PROVIDER`	⚠️ オプション	トンネルプロバイダー	`ngrok`、`zrok`、または `manual`

セキュリティ注意: 認証情報をバージョン管理にコミットしないでください。環境変数または安全なシークレット管理を使用してください。

🛠️ MCPツールリファレンス

支払い作成

`create_payment_onchain`

直接取引用の特定のアドレスで暗号通貨支払いを作成します。

使用する場合: ユーザーが暗号通貨（Bitcoin、ETH、USDCなど）を指定した場合

{
  "amount_eur": 50.0,
  "input_currency": "BTC",
  "notes": "Coffee payment"
}

`create_payment_link`

顧客が暗号通貨を選択できるWebベースの支払いURLを作成します。

使用する場合: 特定の暗号通貨が指定されていない一般的な支払いリクエスト（デフォルトオプション）

{
  "amount_eur": 50.0,
  "url_ok": "https://mystore.com/success",
  "url_ko": "https://mystore.com/cancel",
  "notes": "Order #1234"
}

支払い管理

`get_payment_status`

詳細情報付きで現在の支払いステータスを取得します。

{
  "identifier": "payment_id_here"
}

ステータスコード:

NR (準備未完了): プレ支払いが作成され、暗号通貨が割り当てられていません
PE (保留中): 顧客の支払いを待っています
AC (完了待ち): メモリプールで暗号通貨が検出されました
CO (完了): ブロックチェーンで支払いが確認されました
EX (期限切れ): 支払い期限を超過しました
CA (キャンセル): 支払いがキャンセルされました
FA (失敗): トランザクションの確認に失敗しました

`list_currencies_catalog`

オプションの金額ベースのフィルタリングで利用可能な暗号通貨を取得します。

{
  "filter_by_amount": 25.0
}

`generate_payment_qr`

高品質出力で既存の支払い用のカスタムQRコードを作成します。

{
  "identifier": "payment_id_here",
  "qr_type": "both",
  "size": 512,
  "style": "branded"
}

QRタイプ:

address: 暗号通貨アドレスのみ（顧客が手動で金額を入力）
payment_uri: アドレス + 金額を含む（推奨）
both: 両方のタイプを生成（推奨）
gateway_url: 支払いゲートウェイURLのQR

QRサイズオプション (v1.1.0以降):

デフォルト: 512px（最新のディスプレイ向けに最適化）
範囲: 100px - 2000px
推奨サイズ:
- 512px: モバイルおよびWeb表示
- 800-1200px: 標準印刷
- 1600-2000px: 高品質印刷（ポスター、スタンド）

品質向上 (v1.1.0):

✨ QRパターン用のnearestカーネル補間によるシャープなエッジ
🎯 lanczos3カーネルによる高品質ロゴスケーリング
📦 適応フィルタリング付きPNG圧縮レベル6
🖼️ より鮮明にするためにデフォルトサイズを300pxから512pxに増加

Webhookツール

`get_webhook_events`

Bitnovo Pay APIからリアルタイムで受信したWebhookイベントを照会します。

利用可能な場合: WEBHOOK_ENABLED=true

{
  "identifier": "payment_id_here",
  "limit": 50,
  "validated_only": true
}

`get_webhook_url`

Bitnovoパネルの設定手順付きで公開Webhook URLを取得します。

利用可能な場合: WEBHOOK_ENABLED=true

{
  "validate": true
}

`get_tunnel_status`

トンネル接続ステータス（ngrok、zrok、または手動）を診断します。

利用可能な場合: WEBHOOK_ENABLED=true

{}

📚 ドキュメント

APIツールリファレンス - すべてのMCPツールの詳細ドキュメント
使用例 - 実際の使用例
エラー処理 - エラーコードとトラブルシューティング
Webhookシステム - Webhook設定とトンネル管理

🏗️ 開発

利用可能なスクリプト

npm run build        # Compile TypeScript to JavaScript
npm run dev          # Run development server with hot reload
npm start            # Start production server
npm test             # Run test suite
npm run test:watch   # Run tests in watch mode
npm run lint         # Run ESLint
npm run format       # Format code with Prettier

アーキテクチャ

┌─────────────────┐
│   MCP Tools     │ ← 8 tools: 5 payment + 3 webhook
│ (src/tools/)    │
├─────────────────┤
│   Services      │ ← Business logic: PaymentService, CurrencyService
│ (src/services/) │
├─────────────────┤
│   API Client    │ ← Bitnovo API integration with retry logic
│ (src/api/)      │
├─────────────────┤
│ Webhook Server  │ ← HTTP Express + Event Store + Tunnel Manager
│ (src/webhook-*) │
├─────────────────┤
│   Utilities     │ ← Logging, validation, error handling, crypto
│ (src/utils/)    │
└─────────────────┘

デュアルサーバーアーキテクチャ

MCPサーバーは2つのサーバーを同時に実行できます:

┌─────────────────────────────────────────────────────────┐
│             MCP Bitnovo Pay Server                      │
│                                                         │
│  ┌──────────────┐  ┌──────────────────┐ ┌────────────┐│
│  │ MCP Server   │  │ Webhook Server   │ │  Tunnel    ││
│  │ (stdio)      │  │ (HTTP :3000)     │ │  Manager   ││
│  └──────┬───────┘  └────────┬─────────┘ └──────┬─────┘│
│         │                   │                   │      │
│         │    Event Store    │     Public URL    │      │
│         │   (in-memory)     │   (ngrok/zrok)    │      │
│         └──────────┬────────┴──────────┬────────┘      │
└────────────────────┼───────────────────┼───────────────┘
                     │                   │
            ┌────────┴────────┐  ┌───────┴────────┐
            │                 │  │                │
       Claude Desktop   Bitnovo API    Tunnel Provider
       (MCP Tools)      (Webhooks)    (ngrok/zrok/manual)

🔒 セキュリティ

HTTPSのみ - すべてのAPI呼び出しでHTTPSを使用
HMAC検証 - SHA-256によるWebhook署名検証
リプレイ攻撃防止 - 5分間のTTL付きNonceキャッシング
データプライバシー - 機密情報はログでマスクされます
レートデータなし - 不正確さを防ぐため為替レートは公開されません
ステートレス設計 - ローカル永続化なし、リアルタイムAPIクエリ
自動再接続 - トンネル用に最大10回の指数バックオフ再試行
ヘルスモニタリング - 60秒ごとの接続検証

📄 ライセンス

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

🤝 貢献

リポジトリをフォーク
フィーチャーブランチを作成 (git checkout -b feature/amazing-feature)
変更をコミット (git commit -m 'Add amazing feature')
ブランチにプッシュ (git push origin feature/amazing-feature)
プルリクエストを開く

📞 サポート

問題: GitHub Issues
Bitnovoサポート: https://www.bitnovo.com/
MCPプロトコル: https://modelcontextprotocol.io/

🌟 関連

Model Context Protocol - 公式MCP仕様
Bitnovo Pay - 暗号通貨支払いプラットフォーム
Bitnovo Pay - ドキュメント - Bitnovo Pay公式ドキュメント
Bitnovo Pay - スペイン語ドキュメント - Bitnovo Pay公式ドキュメント（スペイン語）
MCP SDK - TypeScript用公式MCP SDK