bitget-agent-mcp

bitget-agent-mcp — Bitget 公式 MCP 取引サーバー

Model Context Protocol を介して Claude Desktop、Cursor、Continue、Windsurf、ChatGPT を Bitget に接続し、自然言語で暗号資産を取引できます。

クイックスタート · 機能 · 仕組み · インストール · 設定 · セキュリティ · トラブルシューティング · よくある質問

---

概要

bitget-agent-mcp は Bitget の公式 Model Context Protocol（MCP）サーバーで、Claude Desktop、Cursor、Continue、Windsurf、ChatGPT Desktop などのデスクトップ AI エージェントが、自然言語のコマンドで Bitget アカウントを操作できるようにします。

Bitget Unified Trading Account（UTA / v3）API を基盤としており、市場データ、現物、先物、口座・資金管理、サブアカウント、ローン、税務にわたる89 種類の取引操作に対応しています。重要なのは、エンドポイントごとに 1 つのツールを用意してモデルに大量のツールを提示しないことです。その代わりに、厳選された 14 個のインテント動詞からなる、段階的に発見できる小規模なインテント群を公開します（デフォルトプロファイルでは 12 個の動詞に加えて discover と raw を読み込み、合計 14 個のツールを提供します）。これにより、エンドポイントごとにツールを用意するサーバーで発生しがちなコンテキストの肥大化やツール選択の誤りを避けながら、AI ホストにすべての機能を提供します。

Bitget Agent Hub の一部 — CLI、SDK、インストーラー、市場分析スキルを含む、Bitget 公式のオープンソース AI エコシステムです。

---

クイックスタート

前提条件

• Node.js ≥ 20（ダウンロード）
• Bitget API キー（こちらで作成）— 読み取りおよび取引の権限を有効にします
• MCP 対応の AI ホスト（Claude Desktop、Cursor、Continue、Windsurf、ChatGPT Desktop、または stdio MCP クライアント）

ワンステップインストール（推奨）

このプロンプトを AI エージェント（Claude Desktop / Cursor など）に貼り付けます。

Please configure the Bitget MCP Server for my AI tool (requires Node.js 20+):
first ask me which AI tool I use (Claude Desktop / Cursor / Windsurf / ChatGPT
Desktop), then add a server that runs `npx -y @bitget-ai/bitget-agent-mcp` to
that tool's MCP config, with BITGET_API_KEY, BITGET_SECRET_KEY, and
BITGET_PASSPHRASE filled in. Confirm once the Bitget tools have loaded.

エージェントがツールを検出し、npx サーバーエントリを追加して、認証情報を設定し、接続を確認します。

手動インストール

設定ファイルを自分で編集したい場合は、ツールごとの JSON スニペットがある設定に進んでください。コマンドは常に次のとおりです。

npx -y @bitget-ai/bitget-agent-mcp

---

できること

設定すると、AI は自然言語を通じて Bitget の取引機能にネイティブにアクセスできます。いくつか例を示します（すべて実際の機能上の操作に対応しています）。

AI への質問	実行される内容	認証情報
「現在の BTC 価格は？」	market 動詞によるリアルタイムのティッカー	❌ 不要
「BTC の 4 時間足のローソク足を取得して」	market による OHLCV／K 線の履歴	❌ 不要
「BTC 無期限先物の資金調達率は？」	market による資金調達率	❌ 不要
「各アカウントの USDT 残高を表示して」	account_overview によるアカウント概要	✅ 必要
「BTC を 0.1、成行で買って」	order による現物成行注文	✅ 必要
「レバレッジを 10 倍にして BTC のロングを建てて」	account_config ＋ order ／ position	✅ 必要
「未決済注文を一覧表示して」	order（open）	✅ 必要
「現物から先物に 500 USDT を振り替えて」	transfer_funds による内部振替	✅ 必要
「未決済注文をすべてキャンセルして」	order（cancelAll）— 高リスクのため確認を求めます	✅ 必要
「担保を使って USDT を借りて」	loan による暗号資産ローン	✅ 必要

市場データ（market 動詞）は公開情報で、API 認証情報なしで利用できます。アカウントに関わる操作にはすべてキーが必要です。

高度なモード

• --read-only — セッション中のすべての書き込み操作をブロックします。動詞は引き続き表示されますが、注文、振替、キャンセル、出金は Bitget に到達する前に拒否されます。安全に試すのに最適です（--paper-trading とは併用できません）。
• --paper-trading — 署名付きリクエストを Bitget のデモ取引環境に送ります（paptrading: 1 ヘッダーを追加します）。別途デモ API キーが必要です。リスクなしで戦略を練習できます。
• --modules <list> — 必要なモジュールだけを読み込みます。デフォルト：account,trade,market。オンデマンド：strategy、cryptoloans、tax。
• --surface <intent|full> — intent（デフォルト）では厳選された動詞を公開します。full では、基盤となる v3 エンドポイントごとに 1 つのツールも追加で公開します。

---

エージェントの使い方

intent サーフェスは段階的に探索できます。最初にすべてのスキーマを読むのではなく、エージェントは発見 → 詳細確認 → 実行の手順をたどります。

discover({})                                   → list business domains + meta-tools
discover({ domain: "trade" })                  → that domain's verbs, one line each
discover({ tool: "order" })                    → one verb's full input schema (+ its actions)
discover({ tool: "order", action: "place" })   → one action's exact required/optional contract
order({ action: "place", ... })                → execute

プロンプトから動詞と引数がすでに明らかな場合、エージェントは発見を省略して直接呼び出します。discover({ search: "funding" }) は、対象の分野が不明な場合にサーフェス全体をキーワード検索します。2 つのメタツールは常に利用できます。

• discover — サーフェスを段階的に調べます。
• raw — operationId を使って任意の v3 操作にアクセスするための代替手段です。ロングテールにも対応します（実際にはすべての操作が動詞でもカバーされているため、raw はほとんど必要ありません）。

書き込みの安全性

• 通常の書き込みは即時に実行されます。
• 高リスク／取り消し不能な操作（例：cancelAll、withdraw）は、confirm: true を渡さない限り { confirmationRequired: true } を返します。
• すべての書き込みで dryRun: true を指定すると、リクエストを送信せずに、送信されるリクエストをプレビューできます。

MCP ツールのアノテーションは SDK の riskLevel（read／write／high）に基づいているため、ホストはモデルが呼び出す前に破壊的な操作を警告できます。

---

アーキテクチャ

graph TD
    A[AI Host<br/>Claude Desktop / Cursor / …] -->|MCP over stdio| B[bitget-agent-mcp<br/>thin protocol adapter]
    B --> S[@bitget-ai/bitget-agent-sdk<br/>intent verbs · discover · raw<br/>write-safety gate · HMAC signing · retry]
    S -->|HMAC-SHA256 signed| C[Bitget UTA v3 REST API<br/>api.bitget.com]
    D[Environment Variables<br/>BITGET_API_KEY etc.] --> B
    style B fill:#f9f,stroke:#333,stroke-width:2px
    style C fill:#bbf,stroke:#333,stroke-width:2px

仕組み：

1. AI ホストは stdio 経由で npx を使って MCP サーバーをローカルで起動します。ネットワークリスナーやプロキシはありません。
2. 認証情報はホストの設定から環境変数として渡されます。サーバーが認証情報を保存、記録、または中継することはありません。
3. 認証が必要なリクエストはすべてプロセス内で HMAC-SHA256 により署名され、Bitget の公式 API に直接送信されます。
4. レスポンスは MCP 経由で AI との会話に返されます。

発見、意図のルーティング、書き込み安全性のチェック、署名、レスポンスの整形といった処理はすべて、@bitget-ai/bitget-agent-sdk にあります。このパッケージは、その上に構築された薄い stdio アダプターです。

---

インストール

対応 AI ホスト

AI ホスト	ステータス	備考
Claude Desktop	✅	claude_desktop_config.json を使用する、正式にサポートされたホストです
Cursor	✅	デフォルトプロファイルは、余裕を持って40ツールの上限に収まります
Continue	✅	VS Code / JetBrains 拡張機能
ChatGPT Desktop	✅	OpenAI のデスクトップクライアント
Windsurf	✅	Codeium の AI IDE
任意の MCP クライアント	✅	stdio 経由で MCP に対応するものすべて

ステップごとのセットアップ

1. API キーを取得する

1. bitget.com にログインします
2. プロフィール → API 管理 に移動します
3. API キーを作成 をクリックします
4. 読み取り と 取引 の権限を有効にします
5. 次の3つの値をコピーします：API Key、Secret Key、Passphrase

⚠️ セキュリティに関する注意： これらは安全に保管してください。共有したり、バージョン管理にコミットしたりしないでください。

2. ホストを設定する

ワンステッププロンプトを使用するか、ホストの MCP 設定にサーバーを手動で追加します（設定を参照）。

3. 確認する

AI に「利用可能な Bitget ツールを教えてください」と尋ねます。market、order、position、account_overview などの動詞に加えて、discover と raw が表示されるはずです。

---

設定

Claude Desktop

claude_desktop_config.json を編集します：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "bitget": {
      "command": "npx",
      "args": ["-y", "@bitget-ai/bitget-agent-mcp"],
      "env": {
        "BITGET_API_KEY": "your-api-key-here",
        "BITGET_SECRET_KEY": "your-secret-key-here",
        "BITGET_PASSPHRASE": "your-passphrase-here"
      }
    }
  }
}

保存後、Claude Desktop を再起動します。

Cursor

設定 → MCP → 新しいサーバーを追加：

項目	値
コマンド	npx
引数	-y @bitget-ai/bitget-agent-mcp
環境変数	BITGET_API_KEY、BITGET_SECRET_KEY、BITGET_PASSPHRASE

⚠️ Cursor のツール上限： Cursor では、すべてのサーバーを合わせた MCP ツールの合計が 40 個までです。デフォルトの Bitget プロファイルでは 14 個のツール（12 個のインテント動詞 + discover + raw）が読み込まれるため、他のサーバー用に26個分の枠が残ります。--modules all を指定すると 16 個のツールが読み込まれます。

Continue / Windsurf / ChatGPT Desktop / その他の MCP ホスト

同じ npx -y @bitget-ai/bitget-agent-mcp コマンドを使用し、お使いのツールの MCP 設定ドキュメントに従って、環境変数経由で認証情報を渡します。ホストが stdio 経由で MCP に対応していれば動作します。

カスタム設定の例

読み取り専用モード（安全に試せます）：

{ "args": ["-y", "@bitget-ai/bitget-agent-mcp", "--read-only"] }

ペーパートレード（デモ環境 — デモ API キーを使用してください）：

{
  "args": ["-y", "@bitget-ai/bitget-agent-mcp", "--paper-trading"],
  "env": {
    "BITGET_API_KEY": "your-demo-api-key",
    "BITGET_SECRET_KEY": "your-demo-secret-key",
    "BITGET_PASSPHRASE": "your-demo-passphrase"
  }
}

モジュールを追加で読み込む：

{ "args": ["-y", "@bitget-ai/bitget-agent-mcp", "--modules", "account,trade,market,cryptoloans,tax"] }

CLI オプションと環境変数

bitget-agent-mcp [options]

  --modules <list>     account, trade, market, strategy,
                       cryptoloans, tax
                       "all" loads every module.
                       Default: account,trade,market

  --surface <mode>     intent  curated verbs + discover + raw (default)
                       full    ALSO emit one tool per underlying v3 endpoint

  --read-only          Expose only read/query operations; block all writes.
  --paper-trading      Enable Demo Trading mode (requires a Demo API Key).
                       Mutually exclusive with --read-only.
  --help               Show help and exit
  --version            Show version and exit

変数	用途
BITGET_API_KEY	プライベートエンドポイントに必須
BITGET_SECRET_KEY	プライベートエンドポイントに必須
BITGET_PASSPHRASE	プライベートエンドポイントに必須
BITGET_API_BASE_URL	任意の API ベース URL（デフォルトは https://api.bitget.com）
BITGET_TIMEOUT_MS	任意のリクエストタイムアウト（ミリ秒、デフォルトは 15000）
BITGET_MAX_RETRIES	任意の最大通信リトライ回数（デフォルト：SDK のポリシー）

API 認証情報がない場合、成功するのは公開／読み取り（市場データ）操作のみです。

モジュールとインテント動詞

デフォルトプロファイルでは account,trade,market が読み込まれます。全体では 6 個のモジュールと 14 個の厳選されたインテント動詞があります：

モジュール	デフォルト	インテント動詞	操作数
market	✅	market	16
trade	✅	order、position、strategy_order	17
account	✅	account_overview、account_config、repayment、transfer_funds、deposit、withdraw、funds_records、subaccount	39
strategy	必要に応じて	strategy_order を拡張（プラン／TP-SL 注文）	5
cryptoloans	必要に応じて	loan	11
tax	必要に応じて	tax	1

モジュールに関係なく、常に利用できます：discover（イントロスペクション）と raw（operationId を指定して任意の v3 操作にアクセス）。

---

セキュリティ

認証情報の保護

• ✅ マシンの外に出ません — API キーは環境変数からのみ読み込まれ、ログへの記録、ディスクへの書き込み、サーバー経由のプロキシは行われません。
• ✅ ローカルで署名 — 認証が必要なすべてのリクエストは、Bitget の公式 API に直接接続する前に、プロセス内で HMAC-SHA256 により署名されます。
• ✅ stdio 経由でローカル実行 — ネットワークリスナーも、強化が必要なリモートエンドポイントも、テレメトリもありません。

安全モード

• --read-only — セッション中のすべての書き込み操作をブロックします。AI は照会できますが、注文、資金移動、キャンセル、出金はできません。
• --paper-trading — 署名済みリクエストを Bitget のデモ環境に送信します。実際の資金は使用しません。専用のデモ API キーが必要です。
• 書き込み安全ゲート — リスクの高い操作や取り消せない操作には、明示的な confirm: true が必要です。また、書き込み操作では dryRun: true を指定すると、ネットワークに接続せずに事前確認できます。

レート制限

SDK はクライアント側の再試行／レート制限ポリシーを適用し、AI による連続呼び出しが Bitget の API に集中するのを防ぎます。Bitget が 429 を返した場合は、バックオフして自動的に再試行します。

---

トラブルシューティング

「Command not found: npx」

原因： Node.js がインストールされていないか、PATH に設定されていません。 対処法： nodejs.org から Node.js ≥ 20 をインストールし、ターミナル／ホストを再起動してください。

「Authentication failed」または「Invalid API key」

考えられる原因と対処法：

1. API キーに必要な権限がありません → API Management で Read と Trade を有効にしてください。
2. パスフレーズが間違っています → 表示されている 3 つの値をすべて正確にコピーしてください。
3. --paper-trading で本番用キーを使用している（またはその逆） → ペーパートレードにはデモ API キーを使用してください。

「AI がツールを認識しない」

原因： MCP サーバーが正しく設定されていないか、ホストが再起動されていません。 対処法： 設定ファイルが有効な JSON であることを確認し、ホストを完全に再起動してから、*「利用可能な MCP ツールを一覧表示して」*と尋ねてください。

Cursor に表示される Bitget ツールが想定より少ない

原因： 他の MCP サーバーが Cursor の 40 ツール上限を消費しています。Bitget のデフォルトプロファイルには14 個のツールがあります。 対処法： 使用していない MCP サーバーを削除するか、--modules を使って必要なものだけを読み込んでください。

「Rate limit exceeded」

原因： 短時間に呼び出しすぎています。 対処法： SDK が自動的に呼び出しを制限しますが、Bitget 側のレート制限に達した場合は、再試行する前に約 60 秒お待ちください。AI に短時間で数百件の注文を出すよう依頼するのは避けてください。

MCP サーバーが起動しない

確認事項： Node.js のバージョン（node --version ≥ 20）、api.bitget.com へのネットワーク接続、送信 HTTPS がファイアウォールでブロックされていないこと。

---

更新

インストールには npx -y を使用するため、AI ホストの起動時に毎回最新バージョンが自動的に取得されます。手動での更新は不要です。

npm キャッシュを強制的に更新するには：

npx @bitget-ai/bitget-agent-mcp@latest --version

Bitget AI ツールキット全体をまとめてアップグレードするには、agent_hub のインストーラーを使用してください。

---

関連プロジェクト

パッケージ	目的	おすすめの用途
agent-cli	ターミナル AI トレーディングツール（bgc）	Claude Code、Codex CLI、シェルネイティブのエージェント
agent-skill	CLI 用の AI 推論ガイド	エージェントに bgc の正しい使い方を教える
agent-sdk	TypeScript 基盤 SDK	カスタム統合を構築する開発者
bitget-signal	市場分析スキル（API キー不要）	マクロ、オンチェーン、センチメント、テクニカル、ニュース
agent_hub	エコシステムの総合エントリーポイントとインストーラー	Bitget AI ツール全体の概要

---

FAQ

bitget-agent-mcp とは何ですか？

Bitget の公式 MCP（Model Context Protocol）サーバーです。89 個の Bitget UTA v3 操作を、MCP 標準を通じてデスクトップ AI クライアント（Claude Desktop、Cursor、Windsurf、ChatGPT Desktop など）に公開します。これには、厳選された14 個のインテント動詞に加え、イントロスペクションツール discover と、制限を回避するための raw が含まれます。

agent-cli とはどう違いますか？

• bitget-agent-mcp — MCP に対応したデスクトップ AI ホスト（Claude Desktop、Cursor、…）向けです。
• agent-cli（bgc）— シェルでコマンドを実行するターミナル AI（Claude Code、Codex CLI）向けです。

どちらも同じ SDK を基盤とし、同じインテントサーフェスを提供します。利用する AI ツールに合ったほうを選んでください。

エンドポイントごとにツールを1つ用意するのではなく、インテント動詞を使うのはなぜですか？

エンドポイントごとにツールを用意するサーバーでは、エンドポイントごとに1つのツールが公開されるため、モデルのコンテキストが膨らみ、ツール選択の精度が低下します。インテントサーフェスでは、デフォルトのツールリストを14個のツール（12個の動詞＋discover＋raw）に抑えながら、デフォルトで公開される89個すべての操作を直接カバーします。また、必要に応じてrawからoperationIdを指定すれば、その他の操作にもアクセスできます。エージェントは、詳細が必要なときにだけdiscoverを使って情報を掘り下げます。

デフォルトで読み込まれるモジュールはどれですか？

デフォルトでは、account（39個の操作）、trade（17個の操作）、market（16個の操作）の合計72個の操作が読み込まれます。これらは12個のインテント動詞とdiscover、rawを通じて公開され、合計14個のツールになります。--modules strategy,cryptoloans,taxまたは--modules allを指定すると、追加のモジュールを読み込めます（--modules allでは、89個のエンドポイントを対象に14個の動詞を利用できます）。

Cursor にはツール数の上限がありますか？

はい。Cursor では、MCP ツールの合計数が40個に制限されています。Bitget のデフォルトプロファイルが読み込むツールは14個なので、上限内に十分収まります（残り26個）。--modules allを指定した場合は16個のツールになります。

注文の誤発注を防ぐにはどうすればよいですか？

設定の args に"--read-only"を追加してください。セッション中はすべての書き込み操作が拒否されるため、AI は残高や市場を照会できますが、注文、資金移動、キャンセル、出金はできません。

実際の資金を危険にさらさずにテストできますか？

はい。ペーパートレードを利用してください。Demo API Keyを作成し、Demo の認証情報を環境変数に設定して、args に"--paper-trading"を追加します。署名付きリクエストは Bitget の Demo 環境に送信されます。

API キーは安全ですか？

はい。認証情報はホストの MCP 設定内にのみ保存され、サーバー経由でプロキシされることはありません。Bitget に送信される前に HMAC-SHA256 でローカル署名され、このサーバーによってログに記録されたり、ディスクに書き込まれたりすることもありません。

無料で利用できますか？

はい。MIT ライセンスのもと、個人利用も商用利用も無料です。MCP サーバーは Bitget によって無償で保守されています。

対応している AI ツールは何ですか？

Claude Desktop、Cursor、Continue、ChatGPT Desktop、Windsurf、および stdio トランスポートで通信するすべての MCP クライアントに対応しています。

---

コントリビューション

Issue とプルリクエストを歓迎します。

• バグの報告／機能のリクエスト： GitHub Issues
• セキュリティに関する問題： リポジトリの GitHub セキュリティアドバイザリ機能を使って、非公開で報告してください。公開 Issue は作成しないでください。

---

ライセンス

MIT License — 個人利用も商用利用も無料です。

---

_{⚠️ リスクに関する免責事項：暗号資産の取引には相当なリスクが伴います。AI エージェントがお客様に代わって発注した注文については、お客様が単独で責任を負います。実際の取引を始める前に、--read-onlyと--paper-tradingを使って安全に練習してください。過去の運用実績は、将来の成果を保証するものではありません。}

_{Bitget Agent Hub 公式ツール · Bitget のオープンソース AI エコシステムの一部 · 基盤：agent-sdk · その他のインターフェース：agent-cli · agent-skill · 市場シグナル：bitget-signal}