hyperliquid-mcp

Controla tus perps de Hyperliquid desde Claude (o cualquier cliente MCP) usando lenguaje natural.

Documentación

🟢 Hyperliquid MCP

Controla tus perps de Hyperliquid desde Claude (o cualquier cliente MCP) usando lenguaje natural.

"¿Cuál es mi PnL de BTC?" → Claude obtiene tus posiciones y responde en segundos.
"Compra 0.1 ETH a mercado" → Claude coloca la orden a través de la API de Hyperliquid.

Construido con el Protocolo de Contexto de Modelo — el estándar abierto para conectar IA a herramientas externas.

✨ Características

Herramienta	Descripción
`hl_get_all_mids`	Precios de todos los activos
`hl_get_orderbook`	Ofertas/demandas L2 para cualquier activo
`hl_get_meta`	Información de mercado (apalancamiento, tamaño de tick)
`hl_get_candles`	Historial OHLCV (1m → 1d)
`hl_get_user_state`	Posiciones, capital, margen, PnL
`hl_get_open_orders`	Órdenes activas
`hl_get_fills`	Historial de operaciones
`hl_get_user_fills_by_coin`	Historial de operaciones filtrado por moneda, con tasa de aciertos y PnL
`hl_get_funding_history`	Historial de tasas de financiación
`hl_get_predicted_fundings`	Financiación prevista para las próximas 8 horas en todas las plataformas
`hl_get_asset_contexts`	Mark, oráculo, financiación, OI, cambio 24h para BTC/ETH/XRP/SOL
`hl_get_recent_trades`	Cinta en vivo con desequilibrio de compra/venta
`hl_place_order`	Colocar órdenes limitadas o de mercado
`hl_cancel_order`	Cancelar una orden específica
`hl_cancel_all_orders`	Cancelar todas las órdenes (opcional: por moneda)
`hl_close_position`	Cerrar toda la posición
`hl_set_leverage`	Establecer apalancamiento (cruzado o aislado)

🚀 Inicio Rápido

1. Instalación

pip install hyperliquid-mcp

O ejecuta directamente sin instalar:

uvx hyperliquid-mcp

2. Configurar Claude Desktop

Abre ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows) y añade:

Modo solo lectura (posiciones, precios, historial — no se necesita clave privada):

{
  "mcpServers": {
    "hyperliquid": {
      "command": "uvx",
      "args": ["hyperliquid-mcp"],
      "env": {
        "HL_WALLET_ADDRESS": "0xYourWalletAddressHere"
      }
    }
  }
}

Modo trading (colocar órdenes, cancelar, cerrar posiciones):

{
  "mcpServers": {
    "hyperliquid": {
      "command": "uvx",
      "args": ["hyperliquid-mcp"],
      "env": {
        "HL_PRIVATE_KEY": "0xYourPrivateKeyHere"
      }
    }
  }
}

⚠️ Nunca compartas tu clave privada. Permanece en tu máquina — este servidor se ejecuta localmente vía stdio, no se envía ningún dato a ningún lugar excepto a la API oficial de Hyperliquid.

3. Reinicia Claude Desktop y empieza a chatear

What are my open positions?
What's the ETH funding rate this week?
Place a limit order to buy 0.5 SOL at $150

🔧 Configuración Manual (desde el código fuente)

git clone https://github.com/erscoder/hyperliquid-mcp
cd hyperliquid-mcp
pip install -e .
cp .env.example .env
# Edit .env with your wallet address or private key

Luego en claude_desktop_config.json:

{
  "mcpServers": {
    "hyperliquid": {
      "command": "python",
      "args": ["-m", "hyperliquid_mcp"],
      "cwd": "/path/to/hyperliquid-mcp",
      "env": {
        "HL_WALLET_ADDRESS": "0xYourWalletAddressHere"
      }
    }
  }
}

🔒 Seguridad

Tus claves nunca salen de tu máquina. El servidor se ejecuta localmente vía transporte stdio.
Solo lectura por defecto. Establece solo HL_WALLET_ADDRESS si no quieres habilitar el trading.
El trading requiere HL_PRIVATE_KEY. Sin ello, todas las herramientas de trading devuelven un error.
Usa una billetera de trading dedicada con fondos limitados para mayor seguridad.

🤖 Uso en Agentes de IA

MCP no es solo para clientes de chat. Usa hyperliquid-mcp como la capa de trading dentro de cualquier agente autónomo.

LangChain / LangGraph

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "hyperliquid": {
        "command": "uvx",
        "args": ["hyperliquid-mcp"],
        "transport": "stdio",
        "env": {"HL_WALLET_ADDRESS": "0xYourWallet"}
    }
})

tools = await client.get_tools()
# tools now includes hl_get_user_state, hl_get_orderbook, etc.
# Pass them to any LangChain agent or LangGraph node

CrewAI

from crewai import Agent
from crewai_tools import MCPTool

hl_tools = MCPTool.from_server(
    command="uvx",
    args=["hyperliquid-mcp"],
    env={"HL_WALLET_ADDRESS": "0xYourWallet"}
)

trader = Agent(
    role="Trading Analyst",
    goal="Monitor Hyperliquid positions and funding rates",
    tools=hl_tools
)

Agente personalizado (SDK de Python de MCP)

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

server_params = StdioServerParameters(
    command="uvx",
    args=["hyperliquid-mcp"],
    env={"HL_WALLET_ADDRESS": "0xYourWallet"}
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool("hl_get_user_state", {})
        print(result.content)

Ideas para agentes:

Monitor de cartera que alerta cuando las tasas de financiación superan un umbral
Gestor de riesgos que cierra posiciones automáticamente cuando la pérdida supera el límite
Escáner de arbitraje que compara financiación entre activos
Agente de resumen matutino que resume el PnL nocturno y las posiciones abiertas

💬 Otros Clientes MCP

Funciona con cualquier cliente compatible con MCP:

Claude Desktop — ver Inicio Rápido arriba
VS Code (Copilot) — añadir a .vscode/mcp.json
Cursor — añadir a la configuración de MCP
Continue.dev — añadir a la configuración

📄 Licencia

MIT — libre de usar, bifurcar y contribuir.

🌟 Historial de Estrellas

Si esto te ahorró tiempo, ¡una ⭐ ayuda mucho!