Skip to main content
Glama

Hyperliquid MCP Server

by t3rmed
GitHub
Python
MIT License
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Hyperliquid MCP Server

A Model Context Protocol (MCP) server for interacting with the Hyperliquid DEX. This server provides tools for retrieving market data, managing positions, and executing trades on Hyperliquid.

Built with Python 3.11+ and uv package manager, with full Docker support for easy deployment.

Features

Market Data Tools

  • get_all_mids - Get current mid prices for all coins

  • get_l2_book - Get L2 order book snapshot for a specific coin

  • get_candle_snapshot - Get historical candle data

Account Information Tools

  • get_open_orders - Get all open orders

  • get_user_fills - Get trading history (fills)

  • get_user_fills_by_time - Get fills for a specific time range

  • get_portfolio - Get portfolio information including PnL and margin

Trading Tools

  • place_order - Place limit orders

  • place_trigger_order - Place stop-loss or take-profit orders

  • cancel_order - Cancel specific orders

  • cancel_all_orders - Cancel all open orders

Installation

Prerequisites

  • Python 3.11 or higher

  • uv package manager

  • Docker (optional, for containerized deployment)

Local Installation

  1. Clone this repository

  2. Install dependencies with uv:

    uv sync

  3. Run the server:

    uv run python -m hyperliquid_mcp_server.main

Docker Installation

  1. Clone this repository

  2. Build and run with Docker Compose:

    # Production mode make build && make run # Or using docker-compose directly docker-compose up --build

  3. For development with hot reloading:

    # Development mode make dev # Or using docker-compose directly docker-compose --profile dev up --build

Configuration

Configure the server using environment variables:

Required for Trading Operations

  • HYPERLIQUID_PRIVATE_KEY - Your wallet's private key (with 0x prefix)

Optional

  • HYPERLIQUID_WALLET_ADDRESS - Your wallet address (derived from private key if not provided)

  • HYPERLIQUID_TESTNET - Set to "true" for testnet, "false" or unset for mainnet

Example Environment Setup

Create a .env file (not recommended for production):

HYPERLIQUID_PRIVATE_KEY=0x1234567890abcdef... HYPERLIQUID_WALLET_ADDRESS=0xabcdef1234567890... HYPERLIQUID_TESTNET=true

Usage

Using Make Commands

The project includes a Makefile for common operations:

# Install dependencies make install # Run locally (without Docker) make local # Build Docker image make build # Run in production mode make run # Run in development mode make dev # Run tests make test # Format code make format # Clean up Docker resources make clean

Manual Commands

# Local development uv run python -m hyperliquid_mcp_server.main # Docker production docker-compose up --build # Docker development docker-compose --profile dev up --build

With Claude Desktop

Add this server to your Claude Desktop configuration:

Local Installation

{ "mcpServers": { "hyperliquid": { "command": "uv", "args": ["run", "python", "-m", "hyperliquid_mcp_server.main"], "cwd": "/path/to/hyperliq-mcp", "env": { "HYPERLIQUID_PRIVATE_KEY": "0x...", "HYPERLIQUID_TESTNET": "true" } } } }

Docker Installation

{ "mcpServers": { "hyperliquid": { "command": "docker", "args": ["run", "--rm", "-i", "--env-file", ".env", "hyperliquid-mcp-server:latest"], "cwd": "/path/to/hyperliq-mcp" } } }

API Reference

Market Data

get_all_mids

Get current mid prices for all coins.

{}

get_l2_book

Get L2 order book for a specific coin.

{ "coin": "BTC", "nSigFigs": 3 }

get_candle_snapshot

Get historical candle data.

{ "coin": "BTC", "interval": "1h", "startTime": 1640995200000, "endTime": 1641081600000 }

Account Information

get_open_orders

Get open orders for the configured wallet or a specific user.

{ "user": "0x..." // optional }

get_user_fills

Get trading history.

{ "user": "0x..." // optional }

get_portfolio

Get portfolio information.

{ "user": "0x..." // optional }

Trading

place_order

Place a limit order.

{ "assetIndex": 0, "isBuy": true, "price": "50000", "size": "0.1", "timeInForce": "Gtc", "reduceOnly": false, "clientOrderId": "my-order-1" }

place_trigger_order

Place a trigger order (stop-loss/take-profit).

{ "assetIndex": 0, "isBuy": false, "size": "0.1", "triggerPrice": "45000", "isMarket": true, "triggerType": "sl", "reduceOnly": true }

cancel_order

Cancel a specific order.

{ "assetIndex": 0, "orderId": 12345 }

cancel_all_orders

Cancel all open orders.

{}

Security Notes

  • Never share your private key

  • Use testnet for development and testing

  • Consider using environment variables or secure secret management for production

  • This server requires your private key to sign trading transactions

  • Read-only operations (market data, account info) work without a private key

Asset Indices

Common asset indices for Hyperliquid:

  • BTC: 0

  • ETH: 1

  • SOL: 2

  • (Check Hyperliquid documentation for complete list)

Error Handling

The server includes comprehensive error handling:

  • Invalid configurations are reported on startup

  • API errors are caught and returned with descriptive messages

  • Network timeouts are handled gracefully

  • Input validation prevents malformed requests

Development

Project Structure

hyperliquid_mcp_server/ ├── main.py # Main MCP server ├── types/ │ └── hyperliquid.py # Pydantic type definitions ├── utils/ │ ├── hyperliquid_client.py # API client │ └── config.py # Configuration management └── tools/ ├── market_data.py # Market data tools ├── account_info.py # Account information tools └── trading.py # Trading tools

Development Setup

# Install dependencies uv sync # Install with development dependencies uv sync --extra dev # Run tests uv run pytest # Format code uv run black . uv run isort . # Lint code uv run ruff check . uv run mypy .

Docker Development

# Development mode with hot reloading make dev # Shell into container make shell # View logs make logs

License

MIT

Deploy Server
-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

View all tools

Enables interaction with the Hyperliquid DEX for retrieving market data, managing positions, and executing trades. Supports both testnet and mainnet operations with comprehensive trading tools including order placement, cancellation, and portfolio management.

  1. Features
    1. Market Data Tools
    2. Account Information Tools
    3. Trading Tools
  2. Installation
    1. Prerequisites
    2. Local Installation
    3. Docker Installation
  3. Configuration
    1. Required for Trading Operations
    2. Optional
    3. Example Environment Setup
  4. Usage
    1. Using Make Commands
    2. Manual Commands
    3. With Claude Desktop
  5. API Reference
    1. Market Data
    2. Account Information
    3. Trading
  6. Security Notes
    1. Asset Indices
      1. Error Handling
        1. Development
          1. Project Structure
          2. Development Setup
          3. Docker Development
        2. License

          New MCP Servers

          MCP directory API

          We provide all the information about MCP servers via our MCP API.

          curl -X GET 'https://glama.ai/api/mcp/v1/servers/t3rmed/hyperliquid-mcp'

          If you have feedback or need assistance with the MCP directory API, please join our Discord server