Bitnovo Pay

Name: Bitnovo Pay
Author: bitnovo

ローカル

github.com/bitnovo開発ツール453 週間前に更新

リポジトリ

Bitnovo Pay について

Bitnovo Payは、Bitnovo Pay APIを使って暗号資産決済機能を提供するMCPサーバーです。AIエージェントを使う決済業務向けに、決済作成、状態確認、QRコード、Webhookを扱い、ローカルのstdioとクラウドのHTTPモードに対応します。

主な機能

01オンチェーン決済と決済リンクの作成
02決済状態と通貨カタログの確認
03ブランド付きQRコードの生成
04Webhookイベントとトンネル状態の照会
05ngrok、zrok、手動トンネルに対応
06stdioとHTTPトランスポートに対応

活用シーン

01指定した暗号資産でオンチェーン決済を作成
02顧客が通貨を選べる決済リンクを作成
03決済状態を確認してQRコードを生成
04リアルタイムのWebhookイベントを受信

MCP 対応

Bitnovo Payは、決済管理、通貨検索、QRコード生成、Webhook操作のための8種類のMCPツールを公開します。ローカルのstdio接続とリモートのHTTP接続に対応します。

#cryptocurrency #payments #bitnovo #webhooks #qr-codes #blockchain #api-integration

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": [
        "-y",
        "@bitnovopay/mcp-bitnovo-pay"
      ],
      "env": {
        "BITNOVO_DEVICE_ID": "<BITNOVO_DEVICE_ID>",
        "BITNOVO_BASE_URL": "<BITNOVO_BASE_URL>"
      }
    }
  }
}

起動コマンドnpx -y @bitnovopay/mcp-bitnovo-pay

設定が必要な環境変数

BITNOVO_DEVICE_ID

BITNOVO_BASE_URL

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

npm@bitnovopay/mcp-bitnovo-paystdio

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

MCP Bitnovo Pay

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

Bitnovo Pay API との統合により、AI エージェントに暗号資産決済機能を提供する 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 アカウントにつき静的ドメイン 1 つ）
- 🌐 zrok：固定 URL に対応した完全無料のオープンソース
- 🏢 manual：パブリック IP を持つサーバー向け（N8N、Opal、VPS）
複数の LLM に対応：
- 🤖 OpenAI ChatGPT（GPT-5、GPT-4o、Responses API、Agents SDK）
- 🧠 Google Gemini（Gemini 2.5 Flash/Pro 2025 年 9 月版、CLI、FastMCP）
- 🔮 Claude（Claude Desktop、Claude Code）
高品質 QR コード（v1.1.0 以降）：
- 📱 デフォルト解像度が 512px（従来は 300px）で、最新のディスプレイに対応
- 🖨️ プロフェッショナルな印刷向けに最大 2000px まで対応
- ✨ 最適化された補間アルゴリズムにより、エッジが鮮明です
- 🎨 滑らかなロゴの拡大縮小と、Bitnovo Pay のカスタムブランディングに対応
プライバシーをデフォルトで保護 - ログ内の機密データをマスキングし、データの露出を最小限に抑えます
セキュア - HTTPS の強制、HMAC 署名の検証、秘密情報の安全な取り扱い
高い信頼性 - リトライロジックを内蔵し、タイムアウトを処理し、ステートレスに動作します

📋 前提条件

Node.js 18 以降
Bitnovo Pay アカウントと Device ID（Device Secret は任意）
環境設定（以下のセットアップガイドを参照）

⚡ クイックスタート

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

Bitnovo Pay でサインアップします
Bitnovo ダッシュボードから Device ID を取得します
（任意）Webhook 署名検証用の Device Secret を生成します

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 への接続：

Settings → 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`

顧客が暗号資産を選択できる、ウェブベースの支払い 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：モバイルおよびウェブ表示
- 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 分のナンスキャッシュ
データプライバシー - ログ内の機密情報はマスキングされます
レート情報なし - 不正確な情報を防ぐため、為替レートは公開されません
ステートレス設計 - ローカルにデータを永続化せず、リアルタイムで API を照会します
自動再接続 - トンネルに対し、最大 10 回まで指数バックオフで再試行します
ヘルスモニタリング - 60 秒ごとに接続を確認します

📄 ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は 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 - Documentation - Bitnovo Pay の公式ドキュメント
Bitnovo Pay - Documención en Español - Bitnovo Pay の公式ドキュメント（スペイン語）
MCP SDK - TypeScript 用の公式 MCP SDK

Markdown 対応

ログインしてコメント

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。

Bitnovo Pay

Bitnovo Pay について

主な機能

活用シーン

MCP 対応

設定

ツール

詳細

MCP Bitnovo Pay

🚀 特長

📋 前提条件

⚡ クイックスタート

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

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

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

4. 統合をテストする

☁️ クラウドへのデプロイ（v1.2.0 で新登場）

Railway へのデプロイ（推奨）

Docker へのデプロイ

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

📦 インストール方法

オプション A：npx を使用（推奨）

オプション B：リポジトリをクローン（開発向け）

🔧 LLM プラットフォームごとの設定

Claude Desktop（Anthropic）

OpenAI ChatGPT

Google Gemini

環境変数

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

支払いの作成

create_payment_onchain

create_payment_link

支払いの管理

get_payment_status

list_currencies_catalog

generate_payment_qr

Webhook ツール

get_webhook_events

get_webhook_url

get_tunnel_status

📚 ドキュメント

🏗️ 開発

利用可能なスクリプト

アーキテクチャ

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

🔒 セキュリティ

📄 ライセンス

🤝 コントリビューション

📞 サポート

🌟 関連情報

コメント

MCP は初めてですか？

MCP（Model Context Protocol）とは？

MCP サーバーとクライアントの違いは？

ローカルとリモート、どちらを選ぶべき？

Claude や Cursor にサーバーを導入するには？

掲載プロジェクトは審査されていますか？「認証済み」とは？

自分のプロジェクトが掲載されています。どう申請できますか？

`create_payment_onchain`

`create_payment_link`

`get_payment_status`

`list_currencies_catalog`

`generate_payment_qr`

`get_webhook_events`

`get_webhook_url`

`get_tunnel_status`