trading-mcp

Orderly Trading MCP

ローカルにインストールされた orderly CLI を通じて、AI クライアントに Orderly Network の取引機能を提供する MCP サーバーです。

秘密鍵は OS のキーチェーンに保存されます。MCP プロセスが秘密鍵を目にすることはなく、署名を行うこともありません。CLI のコマンド一覧を検出し、引数を検証して、サブプロセスとして CLI を実行するだけです。

MCP client ⇄ stdio ⇄ orderly-trading-mcp ⇄ execFile ⇄ orderly CLI ⇄ Orderly API
                                                     ↳ OS keychain

要件

• Node.js >= 20
• orderly CLI v2.1.1+ を推奨します（v2.0.1 でも動作します）
  • v2.1.1 では、BID/ASK のマーケット短縮形が修正され、価格範囲および最大数量に関する拒否が取引エラーとして分類され、broker-status の DEX 認証が修正されています。
  • v2.1.0 では、Orderly Predict コマンド、faucet-account、説明の充実化と可変長引数に使用する longAbout／numArgs スキーマフィールドが追加されています。
  • v2.0.1 では、MCP は適切に代替動作します。predict プロファイルには Predict ツールがなく、faucet-account もありません（代わりに faucet_usdc を使用してください）。説明は短くなり、可変長引数にはハードコードされた代替値が使用されます。
• CLI でセットアップ済みのウォレット／API キー（orderly auth-list で確認できます）

インストール

# CLI (installs to ~/.local/bin)
curl -fsSL https://orderly.network/cli.sh | sh

# MCP server
npm install -g @orderly.network/trading-mcp
orderly-trading-mcp doctor

doctor は、検出した CLI の候補、選択されたバイナリ、有効なプロファイル／ネットワーク、キーチェーンで確認できるアカウントをすべて表示します。

クライアント設定

確実に動作する方法は、ORDERLY_BIN を明示的に設定することです。GUI クライアントは最小限の PATH で起動することが多いため、ターミナルから orderly が見つかっていても、~/.local/bin が表示されない場合があります。キーチェーンに複数のアカウントがある場合は、デフォルトとして使用するアカウント ID を ORDERLY_MCP_ACCOUNT にも設定してください。

Claude Code／Cursor（.mcp.json または .cursor/mcp.json）：

{
  "mcpServers": {
    "orderly-trading": {
      "command": "npx",
      "args": ["-y", "@orderly.network/trading-mcp"],
      "env": {
        "ORDERLY_BIN": "/Users/you/.local/bin/orderly"
      }
    }
  }
}

VS Code（.vscode/mcp.json）：

{
  "servers": {
    "orderly-trading": {
      "command": "npx",
      "args": ["-y", "@orderly.network/trading-mcp"],
      "env": { "ORDERLY_BIN": "/Users/you/.local/bin/orderly" }
    }
  }
}

OpenCode（opencode.json）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "orderly-trading": {
        "command": ["npx", "-y", "@orderly.network/trading-mcp"],
        "environment": {
          "ORDERLY_BIN": "/Users/you/.local/bin/orderly",
          "ORDERLY_MCP_TIMEOUT_MS": "180000"
        },
        "timeout": { "execution": 190000 }
      }
    }
  }
}

古い OpenCode ビルドでは、非推奨のトップレベル形式 mcp.<name> を使用します。この形式の timeout は単一の整数です。上記の mcp.servers 形式が現行の形式です。

Codex（.codex/config.toml）：

[mcp_servers.orderly-trading]
command = "npx"
args = ["-y", "@orderly.network/trading-mcp"]
env = { ORDERLY_BIN = "/Users/you/.local/bin/orderly" }

ツール

デフォルトの core プロファイルでは、15 個のツールが登録されます。

ツール	種類	用途
auth_list	読み取り	保存済みアカウント（公開 ID のみ）
account_balance	読み取り	トークン保有量
positions_list	読み取り	ポジション、アカウント価値、証拠金
order_list	読み取り	有効な注文
market_price	読み取り	マーク／インデックス／24 時間統計
market_orderbook	読み取り	板の厚さと最良買値／売値
kline	読み取り	ローソク足
order_place	書き込み	無期限注文を発注
order_cancel	書き込み	注文を 1 件キャンセル
order_cancel_all	書き込み	すべての注文をキャンセル
positions_close	書き込み	リデュースオンリーの成行決済
leverage_get	読み取り	現在のレバレッジを取得
leverage_set	書き込み	レバレッジを変更
orderly_commands／orderly_run	メタ	CLI の全機能

それ以外の機能（アルゴ注文／TP-SL 注文、一括注文、Predict、取引履歴、ファンディング、履歴、シンボル、手数料ティア）は、次のエスケープハッチを通じて利用できます。

orderly_commands({ query: "algo" })
orderly_run({
  command: "algo-order-place",
  args: {
    symbol: "PERP_ETH_USDC", side: "SELL", algo_type: "TP_SL",
    quantity: 0.01, tp_trigger_price: 2500, account: "0x..."
  }
})

orderly_run には、共通ポリシーである秘密コマンドのブロックリスト、変更許可リスト、読み取りコマンド許可リスト、読み取り専用モード、メインネットのゲートが適用されます。プロファイルが制御するのは専用ツールの一覧のみです。デフォルトでは、エスケープハッチから引き続き許可されたすべてのコマンドにアクセスできます。ORDERLY_MCP_STRICT_PROFILE=1 を設定すると、orderly_run も選択したプロファイルに制限されます。変更を行う可能性があるため、orderly_run は読み取り専用ではないと注釈されています。このツール経由の読み取りで、クライアントによる追加確認が必要になる場合があります。一覧表示には、専用の読み取りツールを優先してください。

プロファイルを選ぶと、各分野の専用ツールが追加されます。

ORDERLY_MCP_PROFILE	ツール
core（デフォルト）	15
predict	core + Predict ツール 6 個すべて（predict_round を含む。計 21 個）
algo	core + algo_order_place、algo_order_cancel、algo_order_list（計 18 個）
all	審査済みの読み取りコマンドすべて + 許可された取引変更すべて（67 個）
full	all + withdraw、faucet_usdc、faucet_account（70 個。faucet_account には CLI v2.1.0+ が必要）

安全性モデル

変数	デフォルト	効果
ORDERLY_BIN	auto	CLI のパスを明示します。設定されていて無効な場合、フォールバックは行いません
ORDERLY_MCP_PROFILE	core	ツールの範囲（上記を参照）
ORDERLY_MCP_READ_ONLY	off	1 を設定すると、すべての変更操作を無効にします
ORDERLY_MCP_NETWORK	CLI config	デフォルトのネットワークを上書きします
ORDERLY_MCP_ACCOUNT	auto	呼び出しで account が省略された場合のデフォルトのアカウント ID
ORDERLY_MCP_ALLOW_MAINNET	true	0 を設定すると、メインネットでの変更操作を禁止します
ORDERLY_MCP_ALLOW_UNKNOWN_READS	off	1 を設定すると、新しく未レビューの読み取りコマンドを公開します
ORDERLY_MCP_STRICT_PROFILE	off	1 を設定すると、orderly_run の実行先を選択したプロファイルに限定します
ORDERLY_MCP_TIMEOUT_MS	30000	呼び出しごとのタイムアウト
ORDERLY_MCP_MAX_OUTPUT	65536	呼び出しごとに返す最大文字数
ORDERLY_MCP_DEBUG	off	argv／所要時間を stderr に記録します

faucet_account --wait は最大 120 秒かかることがあります。使用する前に ORDERLY_MCP_TIMEOUT_MS を（たとえば 180000 に）引き上げてください。

設計ルール：

• キーが MCP に渡ることはありません。 wallet-create、wallet-import、 wallet-remove、wallet-logout、wallet-register、wallet-add-key、 wallet-revoke-key、auth-import、auth-logout、auth-cleanup、 broker-create、auth-export-key は、orderly_run を含むすべてのプロファイルでブロックされます。auth-export-key は CLI マニフェストでは読み取り専用ですが、秘密鍵を出力するため、明示的に拒否されます。
• 変更操作はフェイルクローズです。 変更できるのは、明示的な許可リストに含まれる取引コマンドだけです。新しい変更系 CLI コマンドは、レビューされるまで表示されません。
• 読み取りもフェイルクローズです。 読み取りコマンドも許可リストに含まれるため、新しい読み取りコマンドがレビューなしで機密データを公開することはありません。ORDERLY_MCP_ALLOW_UNKNOWN_READS=1 を設定すると、この制限を解除できます。
• シェルは使用しません。 CLI は argv 配列を使って起動するため、16 進数のアカウント ID などの値からシェル構文を注入することはできません。
• ハングしません。 stdin を閉じるため、対話型の CLI プロンプトは即座に失敗します。また、すべての呼び出しにタイムアウトが設定されています。
• 変更操作は直列化されます。 そのため、並列のツール呼び出しによる二重送信を防げます。
• まずプレビューします。 --dry-run に対応する変更系ツールでは dry_run 引数を使用でき、説明文では実行前にプレビューするようモデルに指示します。
• 変更操作の自動再試行は行いません。

出力とエラー

CLI のコンパクトな JSON は、サイズが収まる場合、そのまま渡されます。JSON 以外の出力 （たとえば No keys stored...）はテキストとして返されます。応答が ORDERLY_MCP_MAX_OUTPUT を超えると、切り詰められた無効な JSON を返すのではなく、明確なエラーで呼び出しが失敗します。行ごとの success フラグを返すバッチコマンドは、いずれかの行が失敗すると、失敗件数をメッセージに含めてエラーとして報告されます。

エラーには CLI の stderr と、エラーの種類に応じたヒントが含まれます。

種類	対処方法
使用方法／検証	正確な仕様を確認するには orderly_commands を呼び出してください
API／取引の拒否	メッセージを読み、シンボル、価格、数量、証拠金、アカウントの状態を確認してください
認証	auth_list を確認するか、CLI でキーを設定してください
一時的なエラー	少し待ってから再試行してください
複数アカウント	account=<id> を渡すか、ORDERLY_MCP_ACCOUNT を設定してください

CLI の終了コードは、2 が使用方法、3 が認証、4 が取引の拒否、5 が一時的なエラーです。MCP はアカウント／ネットワークのコンテキストを追加し、変更操作の再試行は行いません。

リソース：orderly://schema、orderly://accounts、orderly://config、 orderly://guide。

開発

npm install
npm run typecheck     # tsc --noEmit
npm test              # builds dist/ + 59 unit/protocol tests
npm run build
npm run doctor
node dist/index.js tools   # print the registered tool list

テストでは隔離された偽の CLI（test/fixtures/fake-orderly.mjs）を使用するため、ネットワーク、キーチェーン、実際のバイナリは必要ありません。

CLI のスキーマはサーバーの起動時に一度だけ読み込まれます。CLI のアップグレード後、または ORDERLY_MCP_PROFILE／ORDERLY_BIN の変更後は、MCP サーバーを再起動してください。

リリース

1. package.json、package-lock.json、および server.json 内のすべてのバージョンを更新してから、コミットします。リリースワークフローではタグが package.json と一致することを検証し、レジストリワークフローではすべてのマニフェストのバージョンが一致することを検証します。

2. タグを付けてプッシュします。

   git tag v0.1.1
   git push origin master
   git push origin v0.1.1
   

3. .github/workflows/release.yaml で型チェック、テスト、ビルド、パッケージ化を実行し、provenance（NPM_TOKEN シークレットが必要）付きで npm に公開します。

4. .github/workflows/publish-registry.yaml で server.json を検証し、npm に対象バージョンが公開されるのを待ってから、GitHub OIDC を使用して MCP レジストリに公開します。

MCP のリリースは CLI のリリースとは独立しています。CLI v2.1.1 はリリース済みで、推奨されています。フォールバックを使用すれば v2.0.1 も引き続き動作します。

このサーバーは stdio 専用であり、読み取り専用 MCP とは異なるため、Docker イメージはありません。

意図的に含めていないもの

• キー、ウォレット、認証、ブローカーを管理するツール。
• HTTP トランスポート。取引サーバーをネットワーク経由で公開するには、独自の認証と脅威モデルが必要なため、現時点では stdio のみです。
• CLI の自動ダウンロード。明示的にインストールしてください。インストーラーでリリースのチェックサムが検証されます。