<div align="center">

🚀 Hyperliquid MCP Server

连接 Claude Code 到 Hyperliquid DEX 的力量

由 Caio Vicentino 开发，与 Claude Code 合作

为 Yield Hacker、Renda Cripto 和 Cultura Builder 社区

安装 • 资源 • 示例 • 完整文档 • 常见问题

</div>

---

📖 这个项目是什么？

Hyperliquid MCP Server 是 Anthropic 的 Model Context Protocol (MCP) 的一个完整实现，允许 Claude Desktop 直接与去中心化交易所 Hyperliquid 交互。

通过这个 MCP 服务器，你可以：

• 💬 使用自然语言进行交易 通过 Claude
• 📊 实时分析市场 数据
• 🤖 使用 Claude 的智能自动化策略
• 🔐 完全控制你的密钥和资金

什么是 MCP？

Model Context Protocol (MCP) 是 Anthropic 创建的一个标准，用于将 AI 助手（如 Claude）连接到外部工具和数据源。可以将其视为 Claude Desktop 的“插件”。

什么是 Hyperliquid？

Hyperliquid 是一个高性能的永续期货去中心化交易所 (DEX)，提供：

• 📈 链上订单簿 具有中心化交易所 (CEX) 的性能
• ⚡ 低延迟执行
• 💰 具有竞争力的费用 和资金费率
• 🔒 完全自我托管 — 你控制你的密钥
• 🎯 高达 50 倍的杠杆 在多种资产上

---

✨ 资源

4 类别中的 27 个强大工具

📈 交易 (9 个工具)

• place_order - 限价单和市价单
• place_batch_orders - 批量下单
• cancel_order - 取消特定订单
• cancel_all_orders - 取消所有订单
• modify_order - 修改价格/数量
• place_twap_order - 大额 TWAP 订单
• adjust_leverage - 调整杠杆 (交叉/隔离)
• modify_isolated_margin - 管理隔离保证金
• update_dead_mans_switch - 自动安全系统

👤 账户管理 (8 个工具)

• get_user_state - 完整账户状态
• get_positions - 开仓及损益
• get_open_orders - 开仓订单
• get_user_fills - 交易历史
• get_historical_orders - 订单历史
• get_portfolio_value - 完整投资组合分析
• get_subaccounts - 管理子账户
• get_rate_limit_status - 速率限制状态

📊 市场数据 (6 个工具)

• get_all_mids - 所有对的价格中位数
• get_l2_orderbook - 实时 L2 订单簿
• get_candles - 历史数据 (OHLCV)
• get_recent_trades - 最近的交易
• get_funding_rates - 资金费率
• get_asset_contexts - 市场上下文和统计数据

🔄 实时 WebSocket (4 个工具)

• subscribe_user_events - 账户事件
• subscribe_market_data - 实时市场数据
• subscribe_order_updates - 订单更新
• get_active_subscriptions - 管理订阅

---

🚀 安装

预备条件

• 已安装 Python 3.8+
• 已安装 Claude Desktop (下载)
• 拥有 Hyperliquid 账户及其 API 凭证
• macOS, Linux 或 Windows

快速安装（推荐）

1. 克隆或下载此仓库

   git clone https://github.com/seu-usuario/hyperliquid-mcp-server.git
   cd hyperliquid-mcp-server
   

2. 运行自动安装脚本

   python3 setup.py
   

   脚本会：

   • ✅ 创建 Python 虚拟环境
   • ✅ 安装所有依赖项
   • ✅ 生成配置文件
   • ✅ 自动配置 Claude Desktop
   • ✅ 引导你完成凭证配置

3. 配置你的凭证

   编辑生成的 .env 文件：

   nano .env
   

   添加你的 Hyperliquid 凭证：

   HYPERLIQUID_PRIVATE_KEY=0x...
   HYPERLIQUID_ACCOUNT_ADDRESS=0x...
   HYPERLIQUID_NETWORK=mainnet
   

4. 重新启动 Claude Desktop

   完全关闭并重新打开 Claude Desktop。

5. 验证安装

   在 Claude 中询问：

   你有哪些 Hyperliquid 工具可用？
   

手动安装（高级）

<details> <summary>点击展开手动指令</summary>

# 1. 创建虚拟环境
python3 -m venv venv

# 2. 激活虚拟环境
# macOS/Linux:
source venv/bin/activate
# Windows:
venv\Scripts\activate

# 3. 安装依赖项
pip install -r requirements.txt

# 4. 复制配置模板
cp .env.example .env

# 5. 使用你的凭证编辑 .env
nano .env

# 6. 配置 Claude Desktop
# 将以下内容添加到 Claude 的配置文件中：
# macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
# Linux: ~/.config/Claude/claude_desktop_config.json
# Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hyperliquid": {
      "command": "/完整路径/to/venv/bin/python",
      "args": ["/完整路径/to/server.py"],
      "env": {
        "HYPERLIQUID_PRIVATE_KEY": "你的私钥",
        "HYPERLIQUID_ACCOUNT_ADDRESS": "你的地址"
      }
    }
  }
}

</details>

---

🔑 获取你的凭证

1. 私钥 (Private Key)

从钱包 (MetaMask, Trust Wallet 等) 导出你的私钥：

• 应该是 0x... 格式（0x 后面是 64 个十六进制字符）
• 永远不要与任何人分享此密钥
• 存放在安全的地方

2. 账户地址 (Account Address)

你的以太坊地址（也是 0x... 格式）：

• 你的钱包的公共地址
• 在链上公开可见

⚠️ 凭证的安全性

• 🔒 只在 .env 文件中存储凭证
• ❌ 永远不要 将 .env 提交到 git
• 🧪 使用 测试网 进行初始测试
• 🔄 定期轮换密钥
• 💼 使用单独的钱包进行交易/持有

---

💡 使用示例

一旦安装好，你就可以通过 Claude Desktop 使用自然语言与 Hyperliquid 交互：

📈 交易

限价单

你： "下 0.1 BTC 的买入单，价格为 $45,000"

Claude 将：
✅ 验证你的请求
✅ 下单
✅ 确认订单 ID 和状态

市价单

你： "以市价购买 0.5 ETH"

Claude 将：
✅ 立即执行订单
✅ 显示执行价格和费用
✅ 更新你的仓位

取消订单

你： "取消我所有的 BTC 订单"

Claude 将使用： cancel_all_orders
✅ 取消所有 BTC 订单
✅ 显示取消摘要

批量交易

你： "以 $3000 至 $2900 的价格间隔 $25 下 5 个 ETH 的买单"

Claude 将使用： place_batch_orders
✅ 创建网格订单
✅ 单次交易执行
✅ 确认所有订单

💰 仓位管理

查看仓位

你： "我的开仓和损益是多少？"

Claude 将显示：
📊 所有开仓
💵 入口价格
📈 损益（已实现和未实现）
⚡ 使用的杠杆
⚠️ 平仓价格

平仓

你： "以市价平仓我的 ETH 仓位"

Claude 将：
✅ 平仓整个仓位
✅ 显示退出价格
✅ 计算最终损益

调整杠杆

你： "设置 BTC 交易的杠杆为 10 倍"

Claude 将：
✅ 更新杠杆配置
✅ 显示保证金要求
✅ 提醒风险

📊 市场分析

当前价格

你： "Hyperliquid 上的 BTC 当前价格是多少？"

Claude 将显示：
💰 买价/卖价
📊 标记价格
🎯 指数价格
📈 当前价差

订单簿

你： "显示 ETH 的订单簿"

Claude 将显示：
📗 买单级别
📕 卖单级别
💹 每个级别的流动性
📊 分析价差

历史数据

你： "获取过去 24 小时内 BTC 的 1 小时蜡烛图"

Claude 将返回：
📈 OHLCV 数据
📊 成交量
🔍 可以分析模式

📡 实时数据 (WebSocket)

监控订单簿

你： "订阅 BTC 的订单簿，并在我收到大订单时通知我"

Claude 将：
✅ 连接到 WebSocket
✅ 实时流订单簿
✅ 监控鲸鱼活动
✅ 在发生重大变化时提醒

跟踪交易

你： "实时监控 ETH 的交易"

Claude 将：
✅ 实时交易流
✅ 分析买卖流量
✅ 检测异常活动

🤖 高级策略

条件策略

你： "如果 BTC 价格跌至 $44,000 以下，以 5 倍杠杆购买 0.2 BTC"

Claude 将：
1️⃣ 监控价格 (subscribe_market_data)
2️⃣ 触发时调整杠杆
3️⃣ 下单
4️⃣ 确认执行

投资组合分析

你： "分析我当前投资组合的风险"

Claude 将：
1️⃣ 查询仓位 (get_positions)
2️⃣ 检查余额 (get_user_state)
3️⃣ 计算每种资产的敞口
4️⃣ 评估保证金使用情况
5️⃣ 推荐调整

做市商

你： "在 ETH 的两边放置订单，价差为 1%，每个订单 0.1 ETH"

Claude 将使用： place_batch_orders
✅ 同时下单买卖
✅ 设置做市商网格
✅ 监控并调整

---

🛠️ 高级配置

环境变量

所有配置都由 .env 文件管理：

# 凭证 (必填)
HYPERLIQUID_PRIVATE_KEY=0x...        # 以太坊私钥
HYPERLIQUID_ACCOUNT_ADDRESS=0x...    # 钱包地址

# 网络
HYPERLIQUID_NETWORK=mainnet          # 或 'testnet'

# 端点 (根据网络自动配置)
HYPERLIQUID_API_URL=https://api.hyperliquid.xyz
HYPERLIQUID_WS_URL=wss://api.hyperliquid.xyz/ws

# 可选配置
LOG_LEVEL=INFO                       # DEBUG, INFO, WARNING, ERROR
RATE_LIMIT_WEIGHT=1200              # 每分钟最大 API 权重
HTTP_TIMEOUT=30                     # HTTP 超时 (秒)
WS_TIMEOUT=60                       # WebSocket 超时 (秒)

测试网 vs 主网

开发/测试：

HYPERLIQUID_NETWORK=testnet
HYPERLIQUID_API_URL=https://api.hyperliquid-testnet.xyz
HYPERLIQUID_WS_URL=wss://api.hyperliquid-test

真实交易：

HYPERLIQUID_NETWORK=mainnet
HYPERLIQUID_API_URL=https://api.hyperliquid.xyz
HYPERLIQUID_WS_URL=wss://api.hyperliquid.xyz/ws

⚠️ 注意：始终先在测试网上测试！

---

🔒 安全

API 凭证管理

✅ 做：

• 只在 .env 文件中存储凭证
• 使用测试网进行开发
• 定期轮换凭证
• 配置提款白名单
• 对高风险交易使用隔离保证金
• 安全备份你的凭证

❌ 不要：

• 将 .env 提交到 git
• 在日志或错误消息中共享凭证
• 在开发中使用主网凭证
• 直接在代码中存储凭证
• 与任何人分享你的私钥

私钥的安全性

你的私钥拥有对你账户的 完全控制权：

• 🔐 就像银行密码一样对待
• 🚫 永远不要与任何人分享
• 💾 存储在安全的地方
• 🔧 考虑使用硬件钱包
• 👥 使用不同的账户进行交易/持有

死亡开关

配置一个自动安全系统：

"配置死亡开关为 300 秒"

如果你没有在规定时间内更新开关：

• ⚠️ 所有 开仓订单将被自动取消
• 🛡️ 防止连接丢失
• 🔒 为你的账户提供额外的安全

---

🐛 故障排除

常见问题

<details> <summary><b>❌ "Claude Desktop 中找不到 MCP 服务器"</b></summary>

解决方案：

1. 确保在安装前完全关闭了 Claude Desktop
2. 确认 claude_desktop_config.json 文件位于正确的位置：
   • macOS: ~/Library/Application Support/Claude/
   • Linux: ~/.config/Claude/
   • Windows: %APPDATA%\Claude\
3. 完全重新启动 Claude Desktop（退出，而不是仅关闭窗口）
4. 检查日志 ~/Library/Logs/Claude/

</details> <details> <summary><b>❌ "身份验证失败"</b></summary>

解决方案：

1. 确认 .env 文件中的凭证正确
2. 确认私钥格式正确（应以 0x 开头）
3. 确认账户地址与私钥匹配
4. 使用简单的 API 调用测试凭证
5. 确认使用正确的网络（测试网/主网）

</details> <details> <summary><b>❌ "超过速率限制"</b></summary>

解决方案：

1. 减少请求频率
2. 使用 WebSocket 订阅而不是轮询
3. 组合相关操作
4. 在 .env 中调整 RATE_LIMIT_WEIGHT
5. 使用 get_rate_limit_status 查看状态

</details> <details> <summary><b>❌ "下单失败"</b></summary>

解决方案：

1. 确认有足够的保证金
2. 确认杠杆已设置
3. 确认订单大小满足最小要求
4. 确认价格在合理范围内
5. 确认市场处于交易时间

</details> <details> <summary><b>❌ "WebSocket 断开连接"</b></summary>

解决方案：

1. 检查网络连接
2. 确认 WebSocket URL 正确
3. 确认防火墙允许 WebSocket
4. 重启 MCP 服务器
5. 检查日志以获取错误详情

</details>

调试模式

通过编辑 .env 启用详细日志：

LOG_LEVEL=DEBUG
DEBUG=true

这将显示：

• 📡 所有 API 请求/响应
• 💬 WebSocket 消息
• ⏱️ 速率限制追踪
• 🐛 错误堆栈跟踪

测试服务器

独立测试 MCP 服务器：

# 激活虚拟环境
source venv/bin/activate

# 运行 MCP 检查器
mcp dev server.py

# 这将打开一个交互式测试界面

---

📚 完整文档

API 和 SDK

• Hyperliquid 文档：https://hyperliquid.gitbook.io/hyperliquid-docs/
• Python SDK：https://github.com/hyperliquid-dex/hyperliquid-python-sdk
• WebSocket API：https://hyperliquid.gitbook.io/hyperliquid-docs/websocket-api
• 交易指南：https://hyperliquid.gitbook.io/hyperliquid-docs/trading

Model Context Protocol

• **MCP 规