Bitkub Trading Mcp

インストール

要件： Node.js ≥ 20（node --version で確認できます）。クローンもビルドも不要です。MCP クライアントが初回起動時に npx 経由でパッケージをダウンロードします。

クイックインストール — Claude Code CLI（推奨）

コマンドを 1 つ実行するだけで、JSON の編集は不要です。

公開データのみ（API キーは不要）

市場データ（価格、注文板、ローソク足、公開ティッカーストリーム）のみが必要な場合は、env ブロックを完全に省略してください。

claude mcp add bitkub-trading-mcp -- npx -y bitkub-trading-mcp

9 つの公開 REST ツールと 1 つの公開 WebSocket ティッカーツールは、すぐに利用できます。12 個のセキュアな REST ツールと 2 つのプライベート WebSocket ツールも登録されますが、呼び出すとそれぞれ、キーの追加方法を説明する認証エラーが返されます。

API キーを使用する場合（全機能 — ウォレット、注文および約定取引）

2 つのプレースホルダーの値を、実際の Bitkub キーとシークレットに置き換えてください。生成方法については、API キーを追加するを参照してください。

claude mcp add bitkub-trading-mcp \
  -e BITKUB_API_KEY=your_real_key_here \
  -e BITKUB_API_SECRET=your_real_secret_here \
  -- npx -y bitkub-trading-mcp

すべてのプロジェクトで利用可能にする

上記いずれかのコマンドに -s user を追加してください。

claude mcp add bitkub-trading-mcp -s user -- npx -y bitkub-trading-mcp

これらのいずれかを実行した後、/exit を実行してから、もう一度 claude を実行してください。/mcp で確認できます。

手動インストール（Claude Desktop または設定の手動編集）

Claude Desktop を使用している場合、または設定ファイルを手動で編集する場合は、以下の 3 つの手順に従ってください。

1. MCP クライアントの設定ファイルを開く

クライアント	設定ファイルのパス
Claude Code（すべてのプラットフォーム）	~/.claude.json（Linux/macOS/WSL）または %USERPROFILE%\.claude.json（Windows）
Claude Desktop — macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop — Windows	%APPDATA%\Claude\claude_desktop_config.json
Claude Desktop — Linux	~/.config/Claude/claude_desktop_config.json

ファイルがまだ存在しない場合は、内容を { "mcpServers": {} } として作成してください。

2. bitkub-trading-mcp ブロックを追加する

mcpServers オブジェクト内に、このエントリーを追加してください。ほかの MCP サーバーをすでに設定している場合は、カンマで区切ってください。通常の JSON オブジェクトと同じです。

{
  "mcpServers": {
    "bitkub-trading-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "bitkub-trading-mcp"],
      "env": {
        "BITKUB_API_KEY": "your_api_key_here",
        "BITKUB_API_SECRET": "your_api_secret_here"
      }
    }
  }
}

2 つの your_..._here プレースホルダーを実際の Bitkub キーとシークレットに置き換えてください。生成方法については、以下のAPI キーを追加するを参照してください。

3. クライアントを再起動して確認する

• Claude Code： /exit を実行してから、もう一度 claude を実行します。その後、/mcp を実行してください。
• Claude Desktop： アプリを完全に終了します（Windows ではシステムトレイのアイコンを右クリックして「Quit」、macOS では Cmd+Q）。その後、再起動してください。

bitkub-trading-mcp が 24 個のツールとともに接続されていることを確認できます。初回起動時にパッケージが npm からダウンロードされ（約 5～10 秒）、以降の起動ではキャッシュされたバージョンが使用されます。

BITKUB_API_KEY／BITKUB_API_SECRET が設定されていない場合でも、公開ツールは引き続き動作します。セキュアなツールも登録されますが、呼び出すとそれぞれ、env ブロックの追加方法を説明する認証エラーが返されます。

API キーを追加する

公開 REST ツールと公開ティッカー WebSocket ツールは、キーなしで利用できます。12 個のセキュアな REST ツールと 2 つのプライベート WebSocket ツールを使用するには、MCP クライアント設定の env ブロックに Bitkub API キーとシークレットが必要です。ツールの引数として渡すことは絶対にしないでください。LLM にシークレットが見えることはありません。

1. Bitkubでキーを生成する

1. https://www.bitkub.com/en/api-management にアクセスし、プロンプトが表示されたらログインします。
2. Create new API key をクリックします。
3. 推奨：読み取り専用の権限のみを有効にしてください — Trade と Withdraw のスコープのチェックを外します。このサーバーが公開するエンドポイントは読み取り専用なので、キーに書き込みスコープを付与しても攻撃対象領域が増えるだけです。
4. ダイアログを閉じる前に、API Key と API Secret をコピーします（シークレットは一度しか表示されません）。

2. 環境変数ブロックに貼り付ける

上記で選んだインストール方法の your_..._here プレースホルダーを、実際のキーとシークレットに置き換えます。保存して、MCP クライアントを再起動します。

3. キーが実際に機能することを確認する

ソースをチェックアウトしている場合：

cd /path/to/bitkub-trading-mcp
eval "$(bun -e 'const c=await Bun.file(`${process.env.HOME}/.claude.json`).json();const e=c.mcpServers[`bitkub-trading-mcp`].env;console.log(`export BITKUB_API_KEY=${e.BITKUB_API_KEY}\nexport BITKUB_API_SECRET=${e.BITKUB_API_SECRET}`)')" && bun scripts/test-auth.ts

PASS と表示されれば、Bitkubに対するキーと署名の処理が最初から最後まで正常に機能しています。

それ以外の場合は、Claude に 「Bitkubのウォレットには何が入っていますか？」 と尋ねてください。残高が返ってくれば、キーは機能しています。

公開ツール

ツール	エンドポイント
bitkub_status	GET /api/status
bitkub_servertime	GET /api/v3/servertime (ms)
bitkub_symbols	GET /api/v3/market/symbols
bitkub_ticker	GET /api/v3/market/ticker?sym= — sym を省略すると、すべてのシンボルを1回の呼び出しで取得します
bitkub_bids	GET /api/v3/market/bids?sym=&lmt=
bitkub_asks	GET /api/v3/market/asks?sym=&lmt=
bitkub_depth	GET /api/v3/market/depth?sym=&lmt=
bitkub_trades	GET /api/v3/market/trades?sym=&lmt=
bitkub_tv_history	GET /tradingview/history?symbol=&resolution=&from=&to=

セキュアなツール（読み取り専用、認証必須）

同等のエンドポイントがある場合は Bitkub v4 を使用し、v4 でまだ提供されていないエンドポイントに限り v3 を使用します。v4 ではクエリパラメーター付きの GET を使用します。v3 では主にボディ付きの POST を使用していました。認証の署名方式は v3 と v4 で同じです。

ツール	バージョン	メソッド	エンドポイント	引数（zod 検証済み）
bitkub_balances	v4	GET	/api/v4/wallet/balances	segment?（"funding"）
bitkub_crypto_addresses	v4	GET	/api/v4/crypto/addresses	page?（≥1）、limit?（1–200）、symbol?、network?、memo?
bitkub_crypto_deposits	v4	GET	/api/v4/crypto/deposits	page?、limit?（1–200）、symbol?、status?、created_start?、created_end?（ISO 8601）
bitkub_crypto_withdraws	v4	GET	/api/v4/crypto/withdraws	bitkub_crypto_deposits と同じ形式（読み取り専用の履歴）
bitkub_fiat_accounts	v4	GET	/api/v4/fiat/accounts	page?（1–100）、limit?（1–100） — 両方を指定する必要があります
bitkub_fiat_deposits	v4	GET	/api/v4/fiat/deposit/history	page?、limit?（1–100） — 両方を指定する必要があります
bitkub_fiat_withdraws	v4	GET	/api/v4/fiat/withdraw/history	page?、limit?（1–100） — 両方を指定する必要があります（読み取り専用の履歴）
bitkub_my_open_orders	v3	GET	/api/v3/market/my-open-orders	sym
bitkub_my_order_history	v3	GET	/api/v3/market/my-order-history	sym、p?、lmt?、start?、end?
bitkub_order_info	v3	GET	/api/v3/market/order-info	sym、id、sd、hash?
bitkub_user_limits	v3	POST	/api/v3/user/limits	（なし）
bitkub_user_trading_credits	v3	POST	/api/v3/user/trading-credits	（なし）

認証の署名方式（v3、v4 共通）：X-BTK-APIKEY、X-BTK-TIMESTAMP（Unix ミリ秒）、X-BTK-SIGN = {ts}{METHOD}{path}{?query | body} の HMAC-SHA256、16 進数の小文字。POST の場合、送信時の JSON バイト列そのものに署名します。

参照先：https://github.com/bitkub/bitkub-official-api-docs/blob/master/restful-api.md · https://github.com/bitkub/bitkub-official-api-docs/blob/master/restful-api-v4.md

WebSocket ツール（スナップショット）

各呼び出しで WebSocket を開き、指定された時間のイベントを収集した後に閉じます。ステートレスであり、長期間のサブスクリプションや MCP 通知はありません。

ツール	ストリーム	認証	デフォルト／最大時間
bitkub_ws_ticker_snapshot	market.ticker.<sym>（パブリック）	不要	10 s / 60 s
bitkub_ws_order_updates	order_update（プライベート）	必須	30 s / 120 s
bitkub_ws_match_updates	match_update（プライベート）	必須	30 s / 120 s

引数（すべてのツール）：

• duration_ms? — 整数、ミリ秒単位です。デフォルト値と上限は上記の表のとおりです。
• bitkub_ws_ticker_snapshot.sym — 必須（例：btc_thb）。
• bitkub_ws_order_updates.sym / bitkub_ws_match_updates.sym — data.symbol に対する任意の後処理フィルターです。

レスポンスの形式：

{
  "events": [/* raw Bitkub payloads, in receive order */],
  "count": 0,
  "duration_ms_actual": 30000,
  "stream": "order_update",
  "started_at": "2026-05-10T17:00:00.000Z",
  "ended_at":   "2026-05-10T17:00:30.000Z"
}

時間枠の終了前に WS が閉じた場合、レスポンスには closed_early: true と closed_reason: "..." も含まれます。

競合状態に関する注意： プライベートストリームでは、subscribe の送信後に発生したイベントのみが配信されます。注文の全ライフサイクルを確認するには、注文の発注と並行して bitkub_ws_order_updates を呼び出すか、発注後に bitkub_order_info を呼び出して、確定した最終状態を確認してください。

同時接続数の上限： Bitkub では、API キーごとに同時に接続できるプライベート WebSocket は最大 5 本です。サーバーは「too many concurrent」による切断を検出し、明確なメッセージで通知します。

対象外のストリーム（意図的な除外）： パブリックの market.trade.* チャネル（Bitkub は 2026-05-18 に廃止予定）と、パブリックのオーダーブックチャネル（シンボルではなく数値の pairing_id を使用します。REST の bitkub_depth のほうが適しています）。

参考資料：https://github.com/bitkub/bitkub-official-api-docs/blob/master/websocket-api.md · https://github.com/bitkub/bitkub-official-api-docs/blob/master/private-websocket.md

使用例

平易な英語での依頼内容に基づいて、Claude がツールを呼び出します。「依頼内容」の行はツールを起動するプロンプトの例、「呼び出されるツール」の行は内部で呼び出されるものを示しています（/mcp → ツール履歴で確認できます）。すべての例で、サーバーは登録済みで接続されているものとします。

パブリック REST — 市場データ（キー不要）

依頼内容	呼び出されるツール	備考
「Bitkub の API は現在稼働していますか？」	bitkub_status	手動で注文する前に、プラットフォームのヘルスチェックを行います。
「現在の BTC/THB 価格はいくらですか？」	bitkub_ticker、sym=btc_thb を指定	その時点の価格と 24 時間の変動を一度に取得します。
「BTC、ETH、ADA、USDT の価格を比較して」（複数シンボルのクエリ全般）	bitkub_ticker、引数なし — 1 回の呼び出しで全シンボルを返します	シンボルごとに繰り返し呼び出さないでください。まとめて呼び出すほうが速く、レート制限も回避できます。
「ETH/THB の買い注文を上位 10 件表示して」	bitkub_bids、sym=eth_thb, lmt=10 を指定	未約定の買い注文（bid）です。売り注文には bitkub_asks を使用します。
「BTC/THB のオーダーブックの上位 20 段の厚みは？」	bitkub_depth、sym=btc_thb, lmt=20 を指定	買い注文と売り注文を集計したもので、スプレッド分析に最適です。
「USDT/THB の直近 50 件の取引」	bitkub_trades、sym=usdt_thb, lmt=50 を指定	直近の約定済み取引（タイムスタンプ、価格、売買の別、数量）です。
「Bitkub で利用できるすべての取引ペアを一覧表示して」	bitkub_symbols	正確な sym 文字列がわからない場合に便利です。
「過去 24 時間の BTC/THB の 1 時間足を取得して」	bitkub_tv_history、symbol=BTC_THB, resolution=60, from=<ts>, to=<ts> を指定	チャート表示用の OHLCV です。解像度：1, 5, 15, 60, 240, 1D。
「サーバーの現在時刻は？」	bitkub_servertime	署名付きリクエストが失敗する場合に、クロックのずれを確認します。

プライベート REST — アカウント情報（キー必須、読み取り専用）

話しかける内容	呼び出されるツール	備考
「Bitkub ウォレットには何が入っていますか？」	bitkub_balances	v4 エンドポイントです。各資産の通貨、利用可能額、予約額、合計額を返します。
「BTC/THB の未約定注文を一覧表示して」	bitkub_my_open_orders with sym=btc_thb	現在有効な注文のみです。
「約定済み・キャンセル済みを含む、直近 20 件の BTC/THB 注文を表示して」	bitkub_my_order_history with sym=btc_thb, lmt=20	ページネーション対応の全履歴です。
「注文 ID 123456（買い）のステータスを教えて」	bitkub_order_info with sym=btc_thb, id=123456, sd=buy	特定注文の現在の状態を確認できます。
「ユーザーの取引限度額を教えて」	bitkub_user_limits	THB の日次／月次取引上限です。
「取引クレジットはいくらありますか？」	bitkub_user_trading_credits	Bitkub の取引クレジット残高です（手数料の割引に使用されます）。
「保存済みの暗号資産入金アドレスを一覧表示して」	bitkub_crypto_addresses with limit=50	v4 です。symbol、network、memo で絞り込めます。
「過去 30 日間の暗号資産の入金を表示して」	bitkub_crypto_deposits with created_start=2026-04-10T00:00:00Z, limit=100	日付で絞り込める v4 です。指定できる期間は最大 90 日間です。
「今月の暗号資産の出金を表示して」	bitkub_crypto_withdraws with created_start=2026-05-01T00:00:00Z	入金と同じ形式の v4 です。
「登録済みの銀行口座を一覧表示して」	bitkub_fiat_accounts with page=1, limit=20	page と limit は必ずセットで指定してください — 両方指定するか、どちらも指定しないでください。
「法定通貨の入金履歴」	bitkub_fiat_deposits with page=1, limit=20	同じセット指定ルールです。
「法定通貨の出金履歴」	bitkub_fiat_withdraws with page=1, limit=20	同じセット指定ルールです。

パブリック WebSocket — ライブティッカー（キー不要）

話しかける内容	呼び出されるツール	備考
「BTC/THB の価格を 10 秒間サンプリングして、上昇傾向か下降傾向か教えて」	bitkub_ws_ticker_snapshot with sym=btc_thb, duration_ms=10000	ティッカー更新の配列を返します。Claude が最初と最後の値の差を計算します。
「ETH/THB を 30 秒間監視して、ボラティリティを教えて」	bitkub_ws_ticker_snapshot with sym=eth_thb, duration_ms=30000	成行買いの前に、実際のスプレッドの変動を確認するのに役立ちます。
「BTC が今急騰しましたか？ 15 秒間サンプリングして」	bitkub_ws_ticker_snapshot with sym=btc_thb, duration_ms=15000	REST のポーリングでは見逃すような短時間の値動きを捉えます。

注意点：Bitkub は取引が少ない時間帯に、数秒でパブリックティッカーストリームを終了することがあります。その場合、応答に closed_early: true が含まれます。必要に応じて Claude が再実行できます。

プライベート WebSocket — 注文／約定ストリーム（キー必須）

指示の例	呼び出されるツール	備考
「アカウントを60秒間監視して、注文イベントがあれば報告してください」	bitkub_ws_order_updates with duration_ms=60000	new → open → partial_filled → filled → canceled の遷移を取得します。
「BTC/THB の注文更新だけを90秒間監視してください」	bitkub_ws_order_updates with sym=btc_thb, duration_ms=90000	sym は data.symbol でイベントを事後フィルタリングします。
「60秒待って、約定した取引を教えてください」	bitkub_ws_match_updates with duration_ms=60000	1件の約定が1回のフィルに相当します。平均約定価格と合計手数料を集計します。
「次の90秒間のメイカーとテイカーの約定率を比較してください」	bitkub_ws_match_updates with duration_ms=90000	各約定に is_maker フィールドがあります。

競合状態への対処方法。 プライベート WS は購読後に発生したイベントのみを配信します。注文のライフサイクル全体を取得するには、次のようにします。

「BTC を 0.0001 BTC、270万で指値買いし、同時に order_updates を60秒間監視してください。その後、bitkub_order_info を呼び出して最終状態を確認してください。」

Claude の1回のターンで、3つのツール呼び出しがすべて並行して実行されます。WS がライフサイクルのイベントの大半を取得し、REST の order_info 呼び出しが、初期のイベントを取り逃した場合に最終状態を確認するための正式な情報を提供します。

注：このサーバーには注文の発注機能は含まれていません。発注するには別の取引サーバーを追加するか、Bitkub で手動で注文してください。監視と確認のパターンは、別の方法で発注された注文に対しても引き続き機能します。

複合ワークフロー（1つのプロンプトで複数のツールを使用）

ワークフロー	使用するツール（並行実行）
「BTC/THB の板情報、直近50件の取引を表示し、ティッカーを10秒間監視してください。今が買い時か教えてください。」	bitkub_depth + bitkub_trades + bitkub_ws_ticker_snapshot
「過去24時間を監査してください。現在の残高、昨日以降のすべての暗号資産の入金、未決済注文を確認してください。」	bitkub_balances + bitkub_crypto_deposits（created_start を指定）+ bitkub_my_open_orders（シンボルごと）
「UI で注文が『open』のまま停止しています。REST の状態を取得し、order_updates を30秒間監視して変化があるか確認してください。」	bitkub_order_info + bitkub_ws_order_updates

セキュリティ

• 読み取り専用として設計されています。 このサーバーでは、注文の発注、注文のキャンセル、出金の開始、アドレスの生成は意図的に実装していません。データ取得エンドポイントのみを公開しています。
• 読み取り専用の Bitkub API キーを使用してください。 Bitkub の API キー権限モデルでは、キーを読み取り専用の操作に限定できます。必ずそのように設定してください。サーバー自体は何も拒否しませんが、最小権限のキーを使えば、問題が発生した場合でも取引所側で確実に操作を制限できます。
• 認証情報をツール引数として受け付けることはありません。 MCP クライアントの env ブロックから提供された値を、process.env からのみ読み取ります。LLM がシークレットを参照することはできません。
• シークレットはログに記録されません。 stderr の診断情報には、認証情報が設定されているかどうかのみが含まれ、値は含まれません。
• キーをローテーションするには、クライアント設定の env ブロックを更新して MCP クライアントを再起動してください。サーバーコードの変更は必要ありません。

注記

• すべてのレスポンスは、Bitkub の JSON を変更せずにそのまま返します（フィールドのマッピングは行いません）。
• Bitkub のエンベロープエラー（error != 0）は、元のエラーコードとともに MCP ツールエラーとして通知されます。
• HTTP の非 2xx レスポンスは、ステータスとレスポンス本文とともに通知されます。
• 診断情報は stderr のみに書き込まれます。stdout は MCP トランスポート専用です。