hyperliquid-mcp

from erscoder

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

🔥🔥🔥✓ VerifiedFreeQuick setup

🟢 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_funding_history`	Funding rate history
`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)

🔒 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!

Copy & paste — that's it

pip install hyperliquid-mcp

Before it works, you'll need: HL_WALLET_ADDRESS

🚀 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"
      }
    }
  }
}