Hyperliquid Trader Mcp

中文🇨🇳

Hyperliquid MCP Trader

Model Context Protocol (MCP) を基盤とするトレーディングツールチェーンです。
一般的に使用される Hyperliquid Python SDK のエンドポイントをラップし、MCP ツールとして公開します。

• get_mark_price(symbol)：最新のマーク価格を取得します
• place_omarket/limit(symbol, side, qty, price, tif)：成行注文または指値注文を発注します
• place_spot_market/limit(...)：スポット取引のエントリーポイント（現在の Hyperliquid SDK では未実装のため、呼び出すと NotImplementedError が発生します）
• cancel_order(order_id)：ID で注文をキャンセルします
• get_positions(dex)：現在のポジションを返します（dex は空、perp、または spot を指定できます）
• get_balances(dex)：残高とマージンの概要を返します（dex の指定方法は上記と同じです）

1. 環境のセットアップ

1. uv をインストールします（pip install uv を実行するか、上流のガイドに従ってください）。
2. プロジェクトのルートに仮想環境を作成し、依存関係を同期します。

   uv venv
   uv sync
   

   手動でインストールする場合は、uv pip install -r requirements.txt を実行してください。

3. .env.example を .env にコピーし（または変数を手動でエクスポートし）、実際の認証情報を入力します。

   cp .env.example .env
   # Edit .env:
   # HL_ACCOUNT_ADDRESS=0xYourMainWalletAddress
   # HL_SECRET_KEY=0xYourApiWalletPrivateKey
   # HL_NETWORK=testnet  # or mainnet
   

セキュリティのヒント： Hyperliquid の API ウォレット（取引権限のみ）を使用し、実際の秘密鍵は絶対にコミットしないでください。
任意の変数：HL_API_BASE_URL（カスタムエンドポイント）、HL_SKIP_WS（WebSocket をスキップするには true に設定）、MCP_AUTH_HEADER_VALUE（Authorization ヘッダーに含める必要がある共有シークレット）、MCP_AUTH_HEADER_NAME（ヘッダー名を上書きします。デフォルトは Authorization です）。

2. MCP サーバーの実行

uv run --env-file .env python -m app.mcp_server

.env ファイルは省略可能です。ファイルが存在する場合、ローダーが自動的に読み込みますが、--env-file フラグを省略し、認証情報を環境変数として指定することもできます。

HL_ACCOUNT_ADDRESS=0xYourMainWalletAddress \
HL_SECRET_KEY=0xYourApiWalletPrivateKey \
HL_NETWORK=testnet \
uv run python -m app.mcp_server --transport streamable-http --host 0.0.0.0 --port 9000

一般的な MCP ホストの設定例（疑似 JSON）：

Cherry Studio

{
  "mcpServers": {
    "hyperliquid-trading": {
      "isActive": true,
      "name": "hyperliquid-trading",
      "type": "streamableHttp",
      "description": "hyperliquid-trading",
      "baseUrl": " http://0.0.0.0:9000/mcp",
      "headers": {
        "Authorization": "Bearer your-shared-secret"
      }
    }
  }
}

デフォルトでは、サーバーは stdin/stdout 経由で通信します。これはローカル開発に最適です。
MCP ホスト（Claude Desktop、OpenAI Agents など）と統合するには、ホストの設定に同じコマンドを登録してください。
または、.venv を手動で有効化して python -m app.mcp_server を実行してください。

HTTP または SSE 経由でホストするには、トランスポートとネットワークのパラメーターを指定します。

# Streamable HTTP (defaults to 127.0.0.1:8000/mcp)
uv run python -m app.mcp_server --transport streamable-http --host 0.0.0.0 --port 9000

# SSE (works with OpenAI Agents, default mount path /sse)
uv run python -m app.mcp_server --transport sse

環境変数にも対応しています：MCP_TRANSPORT=streamable-http、FASTMCP_HOST、FASTMCP_PORT など。

MCP_AUTH_HEADER_VALUE が設定されている場合、すべての HTTP/SSE リクエストに、設定されたヘッダーと値のペアを含める必要があります（デフォルトは Authorization:Bearer <value> です）。空にするとチェックは無効になります。

リクエストヘッダーの検証

1. 共有シークレットを設定します：export MCP_AUTH_HEADER_VALUE=super-secret-token。
2. （任意）ヘッダー名を上書きします：export MCP_AUTH_HEADER_NAME=X-Custom-Auth。
3. サーバーを再起動します。ヘッダーがない HTTP/SSE リクエストには、403 Missing or invalid request header が返されます。

Streamable HTTP 呼び出しの例：

curl -H "Authorization: super-secret-token" \
     -H "Content-Type: application/json" \
     -d '{"method":"list_tools","params":{}}' \
     http://127.0.0.1:8000/mcp

ローカルテストでガードを無効にする場合は、MCP_AUTH_HEADER_VALUE をクリアする（または unset する）ことができます。

Docker デプロイ

オプション A – ローカルでビルド

docker build -t hl-mcp .
docker run --rm \
  -e HL_ACCOUNT_ADDRESS=0xYourMainWalletAddress \
  -e HL_SECRET_KEY=0xYourApiWalletPrivateKey \
  -e HL_NETWORK=testnet \
  -e MCP_AUTH_HEADER_VALUE=super-secret-token \
  -p 9000:9000 \
  hl-mcp

オプション B – ビルド済みイメージをプル

docker pull patricleee/hyperliquid-trading-mcp:1.0.0
docker run --rm \
  -e HL_ACCOUNT_ADDRESS=0xYourMainWalletAddress \
  -e HL_SECRET_KEY=0xYourApiWalletPrivateKey \
  -e HL_NETWORK=testnet \
  -e MCP_AUTH_HEADER_VALUE=super-secret-token \
  -p 9000:9000 \
  patricleee/hyperliquid-trading-mcp:1.0.0

オプション C – Docker Compose

すぐに使える docker-compose.yml がプロジェクトのルートに含まれています。.env に通常と同じキーを設定して、起動します。

cp .env.example .env  # edit the values first
docker compose -f docker-compose.yml up -d

3. トラブルシューティング

• HL_ACCOUNT_ADDRESS と HL_SECRET_KEY が、選択したネットワーク（HL_NETWORK）と一致していることを確認してください。
• レート制限（429）やタイムアウトが発生する場合は、HLClient 内にリトライや制限のロジックを追加してください。
• まず必ずテストネットでテストし、ワークフローを検証してからメインネットに切り替えてください。

---

プロジェクト構造は、Hyperliquid の公式およびコミュニティの SDK サンプルと、MCP Python SDK のドキュメントにあるパターンに準拠しています。

HyperLiquid DEX

Model Context Protocol（MCP）とは？