Hyperliquid MCP Server 🚀

Model Context Protocol (MCP) server for Hyperliquid — 48 tools for trading, monitoring, risk management, and security on the Hyperliquid perpetual DEX.

Built on the official hyperliquid-python-sdk with production-grade error handling.

Features

📡 Tier 1 — Monitoring (15 tools)

• Real-time user state, positions, balances

• Open orders, trade history, funding history

• Market data: mid prices, L2 order book, candlesticks

• Sub-accounts, staking, fee structure

💹 Tier 2 — Trading (10 tools)

• Limit, market, and trigger orders

• Bracket orders (entry + TP + SL)

• Position management: modify, close, leverage

• Funding rate impact calculator

⚠️ Tier 3 — Risk Management (10 tools)

• Order risk validation before execution

• Liquidation price estimation

• Margin health monitoring

• Portfolio health check & simulation

• Auto leverage adjustment

🔒 Tier 4 — Security (8 tools)

• Wallet & configuration validation

• Preflight checks before trading

• API Wallet / Agent Mode setup

• Trading limits, rate limiting

• Audit trail & emergency stop

📊 Bonus Analytics (5 tools)

• Position analysis with P&L and risk scoring

• Performance metrics (win rate, Sharpe, drawdown)

• Multi-coin comparison

• Strategy backtesting (MA/RSI/Momentum)

• Market sentiment analysis

Related MCP server: perp-cli

Quick Start

1. Install

git clone https://github.com/samimiair/hyperliquid-mcp.git
cd hyperliquid-mcp
pip install -r requirements.txt

2. Configure

cp .env.example .env
# Edit .env with your wallet details:
#   HYPERLIQUID_PRIVATE_KEY=your_64_char_hex_key
#   HYPERLIQUID_ACCOUNT_ADDRESS=0xYourWalletAddress

3. Run

./run.sh

Or run directly with Hermes:

hermes mcp add hyperliquid --command /path/to/hyperliquid-mcp/run.sh
hermes config set mcp_servers.hyperliquid.cwd /path/to/hyperliquid-mcp
hermes config set mcp_servers.hyperliquid.timeout 120

Environment Variables

Architecture

hyperliquid-mcp/
├── main.py            # MCP server entry point (48 tools)
├── api_client.py      # Hyperliquid API wrapper (SDK-based)
├── trading.py         # Order placement & management
├── monitoring.py      # Market data & state queries
├── risk_mgmt.py       # Risk validation & simulation
├── security.py        # Wallet & configuration checks
├── validators.py      # Input validation
├── rate_limiter.py    # API rate limiting
├── alert_manager.py   # Error & alert handling
├── wallet.py          # (Deprecated) Legacy wallet code
├── run.sh             # Startup script with env validation
├── .env.example       # Configuration template
└── requirements.txt   # Dependencies

Security

• Never commit your .env file — it's in .gitignore

• All secrets are read from environment variables

• The run.sh script validates required env vars before starting

• Use API Wallet / Agent Mode to limit trading permissions

• Emergency stop tool (emergency_stop) closes all positions instantly

License

MIT