Skip to main content
Glama
Hyperliquid MCP

Hyperliquid MCP

by erscoder

๐ŸŸข Hyperliquid MCP

Control your Hyperliquid perps from Claude (or any MCP client) using natural language.

"What's my BTC PnL?" โ†’ Claude fetches your positions and answers in seconds.
"Buy 0.1 ETH at market" โ†’ Claude places the order via Hyperliquid API.

Built with the Model Context Protocol โ€” the open standard for connecting AI to external tools.


โœจ Features

Tool

Description

hl_get_all_mids

Prices for all assets

hl_get_orderbook

L2 bids/asks for any asset

hl_get_meta

Market info (leverage, tick size)

hl_get_candles

OHLCV history (1m โ†’ 1d)

hl_get_user_state

Positions, equity, margin, PnL

hl_get_open_orders

Active orders

hl_get_fills

Trade history

hl_get_user_fills_by_coin

Trade history filtered by coin, with win rate & PnL

hl_get_funding_history

Funding rate history

hl_get_predicted_fundings

Predicted next-8h funding across venues

hl_get_asset_contexts

Mark, oracle, funding, OI, 24h change for BTC/ETH/XRP/SOL

hl_get_recent_trades

Live tape with buy/sell imbalance

hl_place_order

Place limit or market orders

hl_cancel_order

Cancel specific order

hl_cancel_all_orders

Cancel all orders (optional: by coin)

hl_close_position

Close entire position

hl_set_leverage

Set leverage (cross or isolated)


Related MCP server: hyperliquid-mcp

๐Ÿš€ Quick Start

1. Install

pip install hyperliquid-mcp

Or run directly without installing:

uvx hyperliquid-mcp

2. Configure Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and add:

Read-only mode (positions, prices, history โ€” no private key needed):

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

Trading mode (place orders, cancel, close positions):

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

โš ๏ธ Never share your private key. It stays on your machine โ€” this server runs locally via stdio, no data is sent anywhere except Hyperliquid's official API.

3. Restart Claude Desktop and start chatting

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

๐Ÿ”ง Manual Setup (from source)

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

Then in claude_desktop_config.json:

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

๐Ÿ”’ Security

  • Your keys never leave your machine. The server runs locally via stdio transport.

  • Read-only by default. Set only HL_WALLET_ADDRESS if you don't want trading enabled.

  • Trading requires HL_PRIVATE_KEY. Without it, all trading tools return an error.

  • Use a dedicated trading wallet with limited funds for extra safety.


๐Ÿค– Use in AI Agents

MCP is not just for chat clients. Use hyperliquid-mcp as the trading layer inside any autonomous agent.

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
)

Custom agent (MCP Python SDK)

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)

Agent ideas:

  • Portfolio monitor that alerts when funding rates spike above threshold

  • Risk manager that auto-closes positions when drawdown exceeds limit

  • Arbitrage scanner comparing funding across assets

  • Morning briefing agent that summarizes overnight PnL and open positions


๐Ÿ’ฌ Other MCP Clients

Works with any MCP-compatible client:

  • Claude Desktop โ€” see Quick Start above

  • VS Code (Copilot) โ€” add to .vscode/mcp.json

  • Cursor โ€” add to MCP settings

  • Continue.dev โ€” add to config


๐Ÿ“„ License

MIT โ€” free to use, fork, and contribute.


๐ŸŒŸ Star History

If this saved you time, a โญ goes a long way!

Available Tools

13 tools
hl_cancel_all_ordersA

Cancel all open orders, optionally filtered by coin. Requires HL_PRIVATE_KEY in env.

Args: coin: Optional asset symbol to filter (None cancels all)

Inputs: coin. Returns: result

hl_cancel_orderA

Cancel a specific order by order ID. Requires HL_PRIVATE_KEY in env.

Args: coin: Asset symbol e.g. BTC oid: Order ID to cancel

Inputs: coin (required), oid (required). Returns: result

hl_close_positionA

Close the entire position for a specific asset using a market order. Requires HL_PRIVATE_KEY in env.

Args: coin: Asset symbol e.g. BTC, ETH

Inputs: coin (required). Returns: result

hl_get_all_midsA

Get mid prices for all assets on Hyperliquid.

Inputs: no named parameters. Returns: result

hl_get_candlesB

Get OHLCV candles for a specific asset.

Args: coin: Asset symbol e.g. BTC, ETH, SOL interval: 1m, 5m, 15m, 30m, 1h, 4h, 8h, 1d (default 1h) limit: Number of candles to return (default 50)

Inputs: coin (required), interval, limit. Returns: result

hl_get_fillsA

Get your recent trade history (fills). Requires HL_WALLET_ADDRESS or HL_PRIVATE_KEY in env.

Args: limit: Number of recent trades to return (default 50)

Inputs: limit. Returns: result

hl_get_funding_historyB

Get funding rate history for a specific asset.

Args: coin: Asset symbol e.g. BTC, ETH, SOL days: Number of days of history (default 7)

Inputs: coin (required), days. Returns: result

hl_get_metaA

Get metadata for all markets: max leverage, tick size, lot size.

Inputs: no named parameters. Returns: result

hl_get_open_ordersA

Get all your open orders on Hyperliquid. Requires HL_WALLET_ADDRESS or HL_PRIVATE_KEY in env.

Inputs: no named parameters. Returns: result

hl_get_orderbookA

Get L2 orderbook (bids/asks) for a specific asset.

Args: coin: Asset symbol e.g. BTC, ETH, SOL depth: Number of price levels to return (default 10)

Inputs: coin (required), depth. Returns: result

hl_get_user_stateA

Get your Hyperliquid account: positions, equity, margin, unrealized PnL. Requires HL_WALLET_ADDRESS (read-only) or HL_PRIVATE_KEY (trading) in env.

Inputs: no named parameters. Returns: result

hl_place_orderA

Place an order on Hyperliquid. Requires HL_PRIVATE_KEY in env.

Args: coin: Asset symbol e.g. BTC, ETH, SOL is_buy: True for long/buy, False for short/sell size: Position size in coins price: Limit price (None for market order) order_type: limit or market (default limit) reduce_only: Only reduce existing position (default False)

Inputs: coin (required), is_buy (required), size (required), price, +2 more. Returns: result

hl_set_leverageA

Set leverage for a specific asset. Requires HL_PRIVATE_KEY in env.

Args: coin: Asset symbol e.g. BTC, ETH leverage: Leverage multiplier e.g. 5, 10, 20 is_cross: True for cross margin, False for isolated (default True)

Inputs: coin (required), leverage (required), is_cross. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    A4/5.0

    Scored across 13 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose: order management, position control, data queries, leverage setting. No two tools overlap in functionality.

    Naming Consistency5/5

    All tools follow the 'hl_' prefix with consistent verb_noun snake_case pattern (e.g., cancel_order, place_order, get_all_mids). Predictable and uniform.

    Tool Count5/5

    13 tools is well-scoped for a trading platform, covering essential operations without being excessive or sparse.

    Completeness4/5

    Core trading workflow (order placement, cancellation, position closing, market data, account info) is covered. Lacks order modification and detailed trade history, but no critical gaps.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to securely trade on Hyperliquid perpetual exchange, including order placement, position management, market data retrieval, and vault operations via natural language.
      23 PyPI
      24
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to interact with Hyperliquid perpetual futures exchange for market analysis, account management, and risk-managed trading.
      5
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language trading of Hyperliquid perpetual futures, including portfolio checks, market data, order placement with confirmation, and position management.
      MIT