trackmcp
Back to directory
erscoder

hyperliquid-mcp

View on GitHub

hyperliquid-mcp

0 stars PythonOthers Updated Aug 22, 2026
agentsdefidexhyperliquidmcpmodel-context-protocolperpetualstradingtypescript

Documentation

🟢 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

ToolDescription
`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)

🚀 Quick Start

1. Install

bash
pip install hyperliquid-mcp

Or run directly without installing:

bash
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):

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

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

json
{
  "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

code
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)

bash
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`:

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

python
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

python
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)

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

Frequently asked questions

What is hyperliquid-mcp?

hyperliquid-mcp is hyperliquid-mcp

How do I install hyperliquid-mcp?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is hyperliquid-mcp open source?

Yes — it is hosted on GitHub at https://github.com/erscoder/hyperliquid-mcp.

Related MCP tools

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP