内容
# Hyperliquid MCP 服务器
Hyperliquid 永续合约交易使用的模型上下文协议（MCP）服务器，通过官方的 Python SDK 实现。该服务器为 AI 助手提供安全、可靠地访问 Hyperliquid 交易平台的权限。
## 功能
✅ **官方 SDK** - 基于官方的 Hyperliquid Python SDK，正确签名
✅ **完整覆盖** - 所有交易端点：订单、仓位、市场数据、保险库
✅ **安全** - 正确 EIP-712 签名，支持代理模式
✅ **区间订单** - 原子化进入 + 止盈 + 止损订单放置
✅ **市场数据** - 实时价格、订单簿、资金利率、蜡烛图
✅ **实时 WebSocket 状态引擎** - 内存订单簿镜像，实现即时、低延迟读取
✅ **微结构信号** - 服务器计算的 OBI、微价格和价差（bps），约 20 个代币载荷
✅ **交易流信号** - 服务器计算的 CVD、攻击者成交量和交易流不平衡，来自实时交易记录
✅ **蒙特卡罗风险** - 矢量化 GBM 模拟（10,000+ 路径），返回 VaR、终端分布和盈利概率
✅ **账户管理** - 仓位、余额、成交、资金历史
✅ **测试网支持** - 在上线前安全测试策略
## 先决条件
- Python 3.10 或更高版本
- [uv](https://github.com/astral-sh/uv) 或 [uvx](https://github.com/astral-sh/uv) 用于包管理
- 具有存入资金的 Hyperliquid 账户
## 安装
### 使用 uvx（推荐）
```bash
# 从 PyPI 直接安装和运行
uvx --from mcp-hyperliquid hyperliquid-mcp
```
### 使用 pip
```bash
# 使用 pip 安装
pip install mcp-hyperliquid
# 运行
mcp-hyperliquid
```
### 本地开发
```bash
# 克隆并从源代码安装
git clone https://github.com/Dakkshin/hyperliquid-mcp.git
cd hyperliquid-mcp
uv sync
# 本地运行
uv run python -m hyperliquid_mcp.server
```
#### 本地开发配置
如果您从本地源代码运行，请使用此配置：
```json
{
"mcpServers": {
"hyperliquid": {
"command": "uv",
"args": [
"--directory",
"/path/to/hyperliquid-mcp",
"run",
"python",
"-m",
"hyperliquid_mcp.server"
],
"env": {
"HYPERLIQUID_PRIVATE_KEY": "0x1234567890abcdef...",
"HYPERLIQUID_TESTNET": "false"
}
}
}
}
```
替换 `/path/to/hyperliquid-mcp` 为实际的克隆仓库路径。
## 配置
### 1. 在 Hyperliquid 上注册您的钱包
**重要：** 在交易前，您的钱包必须在 Hyperliquid 上注册。
**主网：**
1. 访问 https://app.hyperliquid.xyz
2. 连接您的钱包
3. 从 Arbitrum One 存入资金（任意金额即可注册钱包）
**测试网：**
1. 访问 https://app.hyperliquid-testnet.xyz
2. 连接您的钱包
3. 从水龙头或桥接获取测试网资金
### 2. 配置您的 MCP 客户端
环境变量现在直接在您的 MCP 客户端设置中配置（不再需要 `.env` 文件）。
#### Claude Desktop / Kiro
在您的 `mcp.json` 配置文件中添加：
```json
{
"mcpServers": {
"hyperliquid": {
"command": "uvx",
"args": ["--from", "mcp-hyperliquid", "hyperliquid-mcp"],
"env": {
"HYPERLIQUID_PRIVATE_KEY": "0x1234567890abcdef...",
"HYPERLIQUID_TESTNET": "false"
}
}
}
}
```
**所需环境变量：**
- `HYPERLIQUID_PRIVATE_KEY` - 用于交易签名的钱包私钥
**可选环境变量：**
- `HYPERLIQUID_ACCOUNT_ADDRESS` - 用于代理/API 钱包模式（高级）
- `HYPERLIQUID_TESTNET` - 设置为 "true" 表示测试网， "false" 或省略表示主网
- `HYPERLIQUID_VAULT_ADDRESS` - 用于保险库交易
#### 完整配置示例
```json
{
"mcpServers": {
"hyperliquid": {
"command": "uvx",
"args": ["--from", "mcp-hyperliquid", "hyperliquid-mcp"],
"env": {
"HYPERLIQUID_PRIVATE_KEY": "0x1234567890abcdef...",
"HYPERLIQUID_ACCOUNT_ADDRESS": "0xYourTradingAccountAddress...",
"HYPERLIQUID_TESTNET": "false",
"HYPERLIQUID_VAULT_ADDRESS": "0xVaultAddress..."
}
}
}
}
```
#### 其他 MCP 客户端
根据您的客户端文档配置，使用：
- **命令：** `uvx` 或 `python`
- **参数：** `["--from", "mcp-hyperliquid", "hyperliquid-mcp"]` 或 `["-m", "hyperliquid_mcp.server"]`
- **环境：** 在客户端的环境配置中添加所需环境变量
## 可用工具
### 账户和仓位管理
- **`hyperliquid_get_account_info`** - 获取完整的账户摘要
- **`hyperliquid_get_positions`** - 获取所有开放仓位
- **`hyperliquid_get_balance`** - 获取账户余额和可提现金额
### 订单管理
- **`hyperliquid_place_order`** - 下单
- **`hyperliquid_place_bracket_order`** - 原子化下单 + 止盈 + 止损
- **`hyperliquid_cancel_order`** - 取消特定订单
- **`hyperliquid_cancel_all_orders`** - 取消所有开放订单
- **`hyperliquid_modify_order`** - 修改现有订单
- **`hyperliquid_place_twap_order`** - 下 TWAP 订单（即将推出）
- **`hyperliquid_cancel_twap_order`** - 取消 TWAP 订单（即将推出）
### 订单查询
- **`hyperliquid_get_open_orders`** - 获取所有开放订单
- **`hyperliquid_get_order_status`** - 获取特定订单状态
- **`hyperliquid_get_user_fills`** - 获取交易记录
- **`hyperliquid_get_user_funding`** - 获取资金支付历史
### 市场数据
- **`hyperliquid_get_meta`** - 获取交易所元数据（资产、杠杆等）
- **`hyperliquid_get_all_mids`** - 获取所有资产当前中间价
- **`hyperliquid_get_order_book`** - 获取订单簿深度（前 `depth` 层，每侧默认 5 层；来自实时 WebSocket 镜像）
- **`hyperliquid_get_microstructure`** - 获取密集的边缘级信号（OBI、微价格、价差，服务器端计算）
- **`hyperliquid_get_orderflow`** - 获取密集的交易流信号（CVD、攻击者买入/卖出量、交易流不平衡），服务器端计算
- **`hyperliquid_get_recent_trades`** - 获取近期交易
- **`hyperliquid_get_historical_funding`** - 获取资金利率历史
- **`hyperliquid_get_candles`** - 获取 OHLCV 蜡烛图数据
### 风险和量化
- **`hyperliquid_run_monte_carlo`** - 运行矢量化的 GBM 蒙特卡罗价格模拟，并返回聚合风险配置文件（VaR、终端价格分布、盈利概率），服务器端计算
### 保险库管理
- **`hyperliquid_vault_details`** - 获取保险库详情
- **`hyperliquid_vault_performance`** - 获取保险库绩效指标
### 实用工具
- **`hyperliquid_get_server_time`** - 获取服务器时间戳
## 使用示例
### 示例 1：查看账户余额
```
显示我的 Hyperliquid 账户余额
```
AI 将调用 `hyperliquid_get_balance` 并显示：
- 账户价值
- 使用的保证金
- 可提现金额
- 可用余额
### 示例 2：获取市场数据
```
Hyperliquid 上 SOL 当前价格是多少？显示订单簿。
```
AI 将：
1. 调用 `hyperliquid_get_meta` 查找 SOL 的索引
2. 调用 `hyperliquid_get_all_mids` 获取当前价格
3. 调用 `hyperliquid_get_order_book` 获取深度
默认情况下，`hyperliquid_get_order_book` 返回每侧前 **5** 层（传递 `depth` 获取更多）。订单簿由实时 WebSocket 镜像即时提供，每个响应都带有 `source` 字段（`"websocket"` 或 `"rest"`），以便您了解其新鲜程度。
### 示例 3：衡量市场压力（微结构）
```
HYPE 上目前有买入或卖出压力吗？价差有多紧？
```
AI 调用 `hyperliquid_get_microstructure` 并获取服务器端计算的密集信号（无需原始订单簿解析）：
```json
{"asset":"HYPE","source":"websocket","depth":5,"OBI":0.62,"micro_price":1.452,"mid":1.451,"spread_bps":2.1}
```
- **`OBI`** （订单簿不平衡）- 顶层 `depth` 交易量的买入份额；`>0.5` 表示买入较重（上涨压力）。
- **`micro_price`** - 比普通中间价更快反应的 Stoikov 公平价值。
- **`spread_bps`** - 基点中的买卖价差（收紧 ≈ 流动性/立即移动，扩大 ≈ 薄）。
这比获取原始订单簿的代币成本要低得多 - 如果您只需要读取市场压力而不是检查个别层级，请优先使用它。
### 示例 4：读取交易流（订单流 / CVD）
```
在过去一分钟内，BTC 在 Hyperliquid 上看到的是净买入还是净卖出？
```
AI 调用 `hyperliquid_get_orderflow` （可选 `window_secs`，默认为 60）并获取服务器端从执行交易记录中计算出的密集信号：
```json
{"asset":"BTC","source":"websocket","window_secs":60,"buy_vol":12.34,"sell_vol":9.87,"CVD":2.47,"TFI":0.111,"trades":143,"vwap":61234.5,"last_px":61240.0,"duration_s":59.8}
```
- **`buy_vol` / `sell_vol`** - 攻击者签署的成交量（`"B"` = 买入攻击者，`"A"` = 卖出攻击者）。
- **`CVD`** - 窗口内的累计成交量delta（`buy_vol − sell_vol`）；正值 = 净买入。
- **`TFI`** - `[-1, 1]` 中的交易流不平衡（0 = 平衡）；流动性的类似物 OBI。
- **`vwap` / `last_px` / `trades` / `duration_s`** - 窗口 VWAP、最后打印、交易次数和实际覆盖的持续时间。
`get_microstructure` 读取 * resting book*，而 `get_orderflow` 读取 *executed flow* - 将它们一起使用以查看意图和行动。
### 示例 5：模拟下行风险（蒙特卡罗）
```
如果我持有 BTC 接下来的 7 天，风险有多大？
```
AI 调用 `hyperliquid_run_monte_carlo` （默认值：`1h` 蜡烛图，`lookback_days=30`，`days_forward=7`，`iterations=10000`）。服务器估计最近蜡烛图的波动性，将路径通过矢量化的几何布朗运动模型在 numpy 中运行，并仅返回聚合的风险配置文件：
```json
{"asset":"BTC","interval":"1h","days_forward":7,"lookback_days":30,"drift":"zero","s0":61240.0,"steps":168,"iterations":10000,"sigma_per_step":0.0031,"mu_per_step":0.0,"mean_terminal":61230.4,"median_terminal":61180.2,"p05_terminal":56120.7,"p95_terminal":66540.9,"expected_return":-0.0002,"VaR_5pct":0.0836,"prob_profit":0.497}
```
- **`VaR_5pct`** - 5% 风险价值作为正损失幅度（此处 ≈ 8.4% 最坏情况超过地平线在 5% 位置）。
- **`p05_terminal` / `median_terminal` / `p95_terminal`** - 终端价格分位数，涵盖结果分布。
- **`prob_profit`** - 结束价格高于当前价格的路径份额。
- **`drift`** - 默认 `"zero"` （保守的风险）；传递 `use_historical_drift=true` 使用历史平均回报作为漂移。
只有摘要通过电线传输 - 数千个模拟路径永远不会离开服务器，因此在代币上保持便宜，同时在 Python 中进行大量计算。
### 示例 6：下区间订单
```
在 Hyperliquid 上下区间订单：
- 货币对：SOL-USD
- 方向：买入（做多）
- 数量：4.12 SOL（约 900 美元）
- 入场价：218.00 美元
- 目标价：219.50 美元（+0.7%）
- 止损价：216.80 美元（-0.8%）
```
AI 将：
1. 调用 `hyperliquid_get_meta` 获取 SOL 的资产索引（5）
2. 调用 `hyperliquid_place_bracket_order`，参数：
- asset：5
- isBuy：true
- size： "4.12"
- entryPrice： "218.00"
- takeProfitPrice： "219.50"
- stopLossPrice： "216.80"
这会原子地下 3 个订单：
- 入场订单在 218.00 美元
- 止盈触发器在 219.50 美元（仅减少）
- 止损触发器在 216.80 美元（仅减少）
### 示例 7：查看仓位并平仓
```
显示我的开放仓位。 如果我有 SOL 仓位，以市场价格平仓。
```
AI 将：
1. 调用 `hyperliquid_get_positions`
2. 如果存在 SOL 仓位，则调用 `hyperliquid_place_order`，参数：
- 反向（做多则卖出，做空则买入）
- 市场订单（价格 = "0"）
- 仅减少启用
### 示例 8：查看近期交易活动
```
显示我过去 24 小时的最后 50 笔交易
```
AI 将：
1. 计算时间戳（现在 - 24 小时至现在）
2. 调用 `hyperliquid_get_user_fills`，指定时间范围
3. 格式化和显示结果
## 资产索引参考
使用 `hyperliquid_get_meta` 获取完整列表。常见资产：
| 索引 | 资产 | 索引 | 资产 | 索引 | 资产 |
| ----- | ----- | ----- | ----- | ----- | ----- |
| 0 | BTC | 1 | ETH | 5 | SOL |
| 10 | LTC | 11 | ARB | 14 | SUI |
| 18 | LINK | 25 | XRP | 27 | APT |
## 订单类型
### 限价订单（Good-Till-Cancel）
```python
order_type = {"limit": {"tif": "Gtc"}}
```
### 市价订单（立即或取消）
```python
price = "0" # 将价格设置为 0 即可市价订单
order_type = {"limit": {"tif": "Ioc"}}
```
### 触发订单（止损 / 止盈）
```python
order_type = {
"trigger": {
"triggerPx": "100.5", # 触发价格
"isMarket": False, # 假为限价，真为市价
"tpsl": "tp" # "tp" 为止盈，"sl" 为止损
}
}
```
## 错误处理
### "用户或 API 钱包不存在"
**问题：** 您的钱包未在 Hyperliquid 上注册。
**解决方案：**
1. 访问 app.hyperliquid.xyz（或测试网 URL）
2. 连接您的钱包
3. 存入任意金额从 Arbitrum
4. 这注册了您的钱包
### "订单价值必须至少 $10"
**问题：** 您的订单规模太小。
**解决方案：** 确保 `size * price >= $10`
示例：
- SOL 在 200 美元：至少需要 0.05 SOL
- BTC 在 50,000 美元：至少需要 0.0002 BTC
### "无效签名"
**问题：** 私钥不匹配或签名错误。
**解决方案：**
1. 检查您的 HYPERLIQUID_PRIVATE_KEY 是否正确
2. 确保它与您注册的钱包地址匹配
3. 如果使用代理模式，请验证 HYPERLIQUID_ACCOUNT_ADDRESS
## 代理模式（高级）
代理模式允许 API 钱包为不同的交易账户签署交易。
**用例：** 保持主账户安全，同时允许 API 钱包为交易账户进行交易。
**设置：**
```bash
HYPERLIQUID_PRIVATE_KEY=0xApiWalletPrivateKey...
HYPERLIQUID_ACCOUNT_ADDRESS=0xMainTradingAccountAddress...
```
**要求：**
1. 两个钱包都必须在 Hyperliquid 上注册
2. 主账户必须通过 Hyperliquid UI 批准 API 钱包作为代理
3. 在使用前必须先通过 Hyperliquid UI 执行 `approve_agent` 操作
## 安全最佳实践
1. **从不提交私钥** - 始终使用环境变量
2. **先在测试网上测试** - 在上线前测试策略
3. **设置止损** - 使用区间订单进行风险管理
4. **监控仓位** - 定期检查您的账户
5. **使用代理模式** - 生产环境中保持主账户私钥离线
6. **从小开始** - 先使用最小订单规模测试
## 故障排除
### 服务器启动失败
```bash
# 检查 Python 版本
python --version # 应该为 3.10+
# 检查依赖项
uv sync
# 检查环境变量
cat .env
# 使用调试日志运行
HYPERLIQUID_LOG_LEVEL=DEBUG uvx --from mcp-hyperliquid hyperliquid-mcp
```
### 订单未放置
1. 检查钱包是否注册（参见错误处理）
2. 验证订单规模是否满足 10 美元的最低要求
3. 检查您是否有足够的余额
4. 确保资产索引正确（使用 `get_meta`）
### 找不到资产
```
使用 hyperliquid_get_meta 工具获取所有资产索引
```
AI 将为您显示可交易资产的完整列表及其索引。
## 开发
### 本地开发
```bash
# 克隆仓库
git clone https://github.com/Dakkshin/hyperliquid-mcp.git
cd hyperliquid-mcp
# 安装依赖
uv sync
# 本地运行
uv run python -m hyperliquid_mcp.server
# 运行测试（当可用时）
uv run pytest
```
### 代码结构
```
hyperliquid-mcp/
├── src/
│ └── hyperliquid_mcp/
│ ├── __init__.py
│ └── server.py # 主要的 MCP 服务器实现
├── pyproject.toml # 项目配置
├── README.md # 本文件
└── .env.example # 环境模板
```
### **加入我们的社区**
- **[Telegram 群组](https://t.me/+fC8GWO3zBe04NTY0)** - 获取帮助、分享策略，并与其他交易者联系
## 贡献
欢迎贡献！请：
1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 如果适用，请添加测试
5. 提交拉取请求
## 许可证
MIT 许可证 - 参见 LICENSE 文件获取详细信息
## 资源
- [Hyperliquid 官方文档](https://hyperliquid.gitbook.io/)
- [Hyperliquid Python SDK](https://github.com/hyperliquid-dex/hyperliquid-python-sdk)
- [模型上下文协议](https://modelcontextprotocol.io/)
- [MCP 服务器仓库](https://github.com/modelcontextprotocol/servers)
## 支持
- **问题：** 在 GitHub 上打开问题
- **Hyperliquid 支持：** https://hyperliquid.gitbook.io/hyperliquid-docs/help/support
- **MCP 文档：** https://modelcontextprotocol.io/
## 免责声明
本软件按“原样”提供，不提供任何保证。交易加密货币具有重大风险。仅用您能承受损失的资金进行交易。作者不负责任何交易损失。
---
**交易愉快！ 🚀**
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器