ZebPay MCP Server

Zebpay MCP サーバー

Zebpay の現物取引および先物取引 API 向けの、本番環境対応の TypeScript MCP（Model Context Protocol） サーバーです。トランスポートには stdio のみを使用します。 Model Context Protocol（MCP）は、AI アシスタントがツールやデータソースを安全に呼び出すための標準的な方法です。 ローカルプロセスの実行を通じて接続する Cursor、Claude Desktop、MCP Inspector などの MCP クライアント向けに設計されています。 このサーバーは、厳格な検証、安全なエラー処理、開発者に使いやすい可観測性を備えた、市場データと取引の両方のワークフローを提供します。

このサーバーが提供する機能

• 公開市場データツール（現物取引＋先物取引）
• 非公開の取引／アカウントツール（API 認証情報が必要です）
• エージェントのワークフロー向けの MCP リソースとプロンプト
• Zod によるリクエスト検証
• 構造化されたエラー処理と、オプションのファイルログ記録

特長

• MCP クライアントとの安全なローカル連携を実現する、stdio 専用の MCP サーバー
• 公開操作と認証が必要な操作の両方を含む、現物取引および先物取引 API の対応
• 非公開エンドポイント向けの HMAC ベースの認証済みリクエストフロー
• 入力検証と正規化された MCP エラーレスポンス
• 外部リクエストの再試行とタイムアウト制御
• デバッグと監査に役立つ、オプションの構造化ファイルログ記録

対応ツール

現物取引（公開＋非公開）

• 市場データ：ティッカー、オーダーブック、取引、ローソク足、取引所情報、通貨
• 取引：成行注文／指値注文の発注、注文のキャンセル、シンボル指定によるキャンセル、全注文のキャンセル
• アカウント：残高、未決済注文、注文履歴、取引履歴、取引所手数料
• ツール名の例：
  • zebpay_public_getTicker
  • zebpay_public_getOrderBook
  • zebpay_spot_placeMarketOrder
  • zebpay_spot_placeLimitOrder
  • zebpay_spot_getBalance

先物取引（公開＋非公開）

• 市場データ：ヘルスステータス、市場、マーケット情報、オーダーブック、24 時間ティッカー、集約された取引
• 取引／アカウント：ウォレット残高、注文の発注、証拠金の追加／削減、未決済注文、ポジション
• 履歴：注文履歴、関連注文、取引履歴、トランザクション履歴
• ツール名の例：
  • zebpay_futures_public_getMarkets
  • zebpay_futures_public_getOrderBook
  • zebpay_futures_placeOrder
  • zebpay_futures_getWalletBalance
  • zebpay_futures_getPositions

技術スタック

• Node.js（ESM）
• TypeScript
• @modelcontextprotocol/sdk
• undici
• zod

プロジェクト構成

src/
├── index.ts                  # Stdio MCP server entrypoint
├── mcp/                      # Tools, resources, prompts, MCP errors/logging
├── private/                  # Authenticated Zebpay clients
├── public/                   # Public market-data clients
├── security/                 # Credentials + signing helpers
├── http/                     # Shared outbound HTTP client to Zebpay APIs
├── validation/               # Schemas and validation helpers
├── utils/                    # Caching, metrics, formatting, file logging
└── types/                    # Shared response types

前提条件

• Node.js 20+
• npm 9+
• Zebpay API の認証情報（非公開ツール用）
• 公式の ZebPay API ポータルから API キー／シークレットを作成してください：https://api.zebpay.com/

ZebPay API キーの作成

この MCP サーバーの API 認証情報を生成するには、以下の手順に従ってください。

1. ZebPay API ポータルを開きます：https://api.zebpay.com/
2. ZebPay アカウントにサインインします。
3. API Trading に移動し、Create New API Key をクリックします。
4. キーの詳細を入力します。
   • キー名（例：zebpay-mcp-local）
   • 必要な権限（市場／アカウントの確認には読み取り専用、必要な場合のみ取引権限を付与）
   • 任意の IP ホワイトリスト（セキュリティ強化のため推奨）
5. OTP 認証を完了します。
6. 以下をコピーして保存します。
   • API Key
   • Secret Key（一度だけ表示されます）

次に、ローカルの .env ファイルに追加します。

ZEBPAY_API_KEY=your_api_key
ZEBPAY_API_SECRET=your_api_secret

セキュリティに関する注意事項：

• API キー／シークレットを git にコミットしないでください。
• 最小限の権限を API に付与してください。
• キーが漏えいした場合は、直ちにローテーションしてください。

セットアップ

git clone <your-repo-url>
cd zebpay-mcp-server
npm install
cp env.example .env

.env を更新します（すべての値は環境から読み取られ、コード内にフォールバックのデフォルト値はありません）。

ZEBPAY_API_KEY=your_api_key    # Use the API key from the step above
ZEBPAY_API_SECRET=your_api_secret    # Use the Secret key from the step above
ZEBPAY_SPOT_BASE_URL=https://sapi.zebpay.com/api/v2
ZEBPAY_FUTURES_BASE_URL=https://futuresbe.zebpay.com/api/v1
ZEBPAY_MARKET_BASE_URL=https://www.zebapi.com/api/v1/market
MCP_TRANSPORTS=stdio
LOG_LEVEL=info
HTTP_TIMEOUT_MS=15000
HTTP_RETRY_COUNT=2

ビルドと実行

npm run build
npm start

ファイルへのログ記録（任意）：

npm run start:log

MCP クライアントの設定（Stdio）

MCP クライアント設定の例：

{
  "mcpServers": {
    "zebpay": {
      "command": "node",
      "args": [
          "/absolute/path/to/zebpay-mcp-server/dist/index.js"
        ],
      "env": {
        "ZEBPAY_API_KEY": "YOUR_API_KEY_HERE",
        "ZEBPAY_API_SECRET": "YOUR_API_SECRET_HERE",
        "LOG_LEVEL": "info"
      }
    }
  }
}

こちらも参照してください：mcp-config.json.example。

環境変数

変数	必須	説明	値の例
ZEBPAY_API_KEY	はい	Zebpay API キー（プライベートツールに必要）	YOUR_API_KEY_HERE
ZEBPAY_API_SECRET	はい	Zebpay API シークレット（プライベートツールに必要）	YOUR_API_SECRET_HERE
MCP_TRANSPORTS	はい	stdio である必要があります	stdio
ZEBPAY_SPOT_BASE_URL	はい	スポット API のベース URL	https://www.zebapi.com/api/v2
ZEBPAY_FUTURES_BASE_URL	はい	先物 API のベース URL	https://futures-api.zebpay.com/api/v1
ZEBPAY_MARKET_BASE_URL	はい	マーケット API のベース URL	https://www.zebapi.com/api/v1/market
LOG_LEVEL	はい	debug、info、warn、error	info
LOG_FILE	いいえ	ログのファイルパス	logs/mcp-server.log
HTTP_TIMEOUT_MS	はい	外部リクエストのタイムアウト（ms）	15000
HTTP_RETRY_COUNT	はい	外部リクエストの再試行回数	2

開発者向けコマンド

npm run build
npm test
npm run test:watch
npm run logs
npm run logs:watch
npm run logs:errors
npm run logs:stats
npm run logs:clear

ロギング

• ログ用ツールと例：scripts/README.md
• ロギングの全ドキュメント：docs/LOGGING.md
• ログを Git に含めないでください（logs/ は無視されます）

問題

バグを見つけた場合や、機能をリクエストしたい場合はどうすればよいですか？

• このリポジトリの GitHub Issues タブから issue を作成してください。
• <your-org> と <your-repo> を置き換えて、次の直接リンクを使用することもできます：
  • バグ報告：https://github.com/<your-org>/<your-repo>/issues/new?template=bug_report.md
  • 機能リクエスト：https://github.com/<your-org>/<your-repo>/issues/new?template=feature_request.md
• トリアージを迅速化するため、次の情報を含めてください：
  • 使用した MCP クライアント（Cursor／Claude Desktop／その他）
  • Node.js のバージョンと OS
  • 最小限の再現手順
  • 関連するログ（シークレットは伏せてください）

ライセンス

MIT