Hyperliquid MCP 交易工具链

基于模型上下文协议（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
   # 编辑 .env:
   # HL_ACCOUNT_ADDRESS=0xYourMainWalletAddress
   # HL_SECRET_KEY=0xYourApiWalletPrivateKey
   # HL_NETWORK=testnet  # 或 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"
      }
    }
  }
}

默认情况下，服务器通过标准输入/输出通信，这非常适合本地开发。
要与MCP主机（如Claude Desktop，OpenAI代理）集成，请在主机配置中注册相同命令。
或者手动激活.venv并运行python -m app.mcp_server。

要通过HTTP或SSE托管，指定传输和网络参数：

# 流式HTTP（默认为127.0.0.1:8000/mcp）
uv run python -m app.mcp_server --transport streamable-http --host 0.0.0.0 --port 9000

# SSE（与OpenAI代理兼容，默认挂载路径/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响应。

流式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  # 先编辑值
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

什么是模型上下文协议（MCP）？