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（设为 true 可跳过 WebSocket）、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（或取消设置）。

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)？