kukapay/hyperliquid-info-mcp

An MCP server that provides real-time data and insights from the Hyperliquid perp DEX for use in bots, dashboards, and analytics.
Features
- **User Data Queries**:
- get_user_state: Fetch user positions, margin, and withdrawable balance for perpetuals or spot markets.
- get_user_open_orders: Retrieve all open orders for a user account.
- get_user_trade_history: Get trade fill history with details like symbol, size, and price.
- get_user_funding_history: Query funding payment history with customizable time ranges.
- get_user_fees: Fetch user-specific fee structures (maker/taker rates).
- get_user_staking_summary & get_user_staking_rewards: Access staking details and rewards.
- get_user_order_by_oid & get_user_order_by_cloid: Retrieve specific order details by order ID or client order ID.
- get_user_sub_accounts: List sub-accounts associated with a main account.
- **Market Data Tools**:
- get_all_mids: Get mid prices for all trading pairs.
- get_l2_snapshot: Fetch Level 2 order book snapshots for a specific coin.
- get_candles_snapshot: Retrieve candlestick data with customizable intervals and time ranges.
- get_coin_funding_history: Query funding rate history for a specific coin.
- get_perp_dexs: Fetch metadata about perpetual markets (using meta).
- get_perp_metadata & get_spot_metadata: Get detailed metadata for perpetual and spot markets, with optional asset contexts.
- **Analysis Prompt**:
- analyze_positions: A guided prompt to analyze user trading activity using relevant tools.
- **ISO 8601 Support**: Time-based queries (get_candles_snapshot, get_coin_funding_history, get_user_funding_history) accept ISO 8601 time strings for precise data filtering.
Installation
Prerequisites
- **Python 3.10**: Required by the Hyperliquid Python SDK.
- A valid Hyperliquid account address for user-specific queries.
- uv or pip for package management.
Steps
1. **Clone the Repository**:
2. **Install Dependencies**:
Using uv:
Usage
Running the Server
Run the server in development mode with MCP Inspector:
Or install it for use in Claude Desktop:
Example Usage
Using the MCP Inspector or Claude Desktop, you can interact with the server using natural language prompts. Below are examples of how to trigger the analyze_positions prompt and individual tools conversationally.
1. **Analyze Trading Positions**:
- **Prompt**:
"Please analyze the trading activity for my Hyperliquid account with address 0xYourAddress. Provide insights on my positions, open orders, and recent trades."
- **Behavior**:
This triggers the analyze_positions prompt, which uses get_user_state, get_user_open_orders, get_user_trade_history, get_user_funding_history, and get_user_fees to fetch data and generate a risk/performance analysis.
- **Example Output**:
2. **Fetch User State**:
- **Prompt**:
"Show me the current state of my Hyperliquid account 0xYourAddress, including my positions and margin details for perpetuals."