Prepare the server locally
Run this once before adding it to Claude Code.
git clone https://github.com/YOUR_USERNAME/hyperliquid-mcp
cd hyperliquid-mcp
python -m venv venv
source venv/bin/activate
pip install -r requirements.txtRegister it in Claude Code
claude mcp add -e "HL_WALLET_ADDRESS=${HL_WALLET_ADDRESS}" -e "HL_PRIVATE_KEY=${HL_PRIVATE_KEY}" hyperliquid-mcp -- python /absolute/path/to/hyperliquid-mcp/server.pyReplace any placeholder paths in the command with the real path on your machine.
HL_WALLET_ADDRESSHL_PRIVATE_KEY+ 2 optionalMake your agent remember this setup
hyperliquid-mcp's config, env vars, and the gotchas you hit — recalled in every future Claude Code, Cursor, and Codex session.
npx conare@latestFree · one command · indexes the sessions already on disk. Set up in the browser instead →
What it does
- Real-time market data fetching
- Portfolio value and position tracking
- Paper trading mode for safe testing
- Automated order execution and management
- Risk management tools including stop-loss and liquidation monitoring
Tools 8
get_portfolio_valueAccount balance, equity, margin, unrealized PnLget_positionsAll open perp positions with PnL and leverageget_orderbookLive bid/ask for any marketget_funding_ratesCurrent + predicted funding across all perpsget_liquidation_priceDistance from liquidation for each positionplace_orderMarket or limit order (paper trading by default)cancel_orderCancel one or all open ordersset_stop_lossSet a reduce-only stop-loss triggerEnvironment Variables
HL_WALLET_ADDRESSrequiredYour Hyperliquid wallet addressHL_PRIVATE_KEYrequiredYour Hyperliquid private keyHL_TESTNETSet to true to use testnetPAPER_TRADINGSet to true to enable paper trading modeTry it
Original README from samklein952-hub/hyperliquid-mcp
🚀 Hyperliquid MCP Server
The first MCP server for Hyperliquid — trade perps, check positions, and manage risk via natural language in Claude, ChatGPT, or any MCP-compatible AI agent.
⚡ What You Can Do
Ask Claude in plain English:
"What's my Hyperliquid portfolio worth?" "Show me my open positions and unrealized PnL" "What's the order book for ETH perp right now?" "Which perps have negative funding I can take advantage of?" "How far am I from liquidation on my BTC long?" "Paper trade: buy 0.1 ETH at market" "Set a stop-loss on my SOL position at $120"
🛠️ Tools
| Tool | Description |
|---|---|
get_portfolio_value |
Account balance, equity, margin, unrealized PnL |
get_positions |
All open perp positions with PnL and leverage |
get_orderbook |
Live bid/ask for any market |
get_funding_rates |
Current + predicted funding across all perps |
get_liquidation_price |
Distance from liquidation for each position |
place_order |
Market or limit order (paper trading by default) |
cancel_order |
Cancel one or all open orders |
set_stop_loss |
Set a reduce-only stop-loss trigger |
🚀 Quick Start
1. Clone + Install
git clone https://github.com/YOUR_USERNAME/hyperliquid-mcp
cd hyperliquid-mcp
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
2. Configure
cp .env.example .env
# Edit .env with your wallet address
# Leave PAPER_TRADING=true until you're ready for live trading
3. Connect to Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or
%APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"hyperliquid": {
"command": "python",
"args": ["/absolute/path/to/hyperliquid-mcp/server.py"],
"env": {
"HL_WALLET_ADDRESS": "0xYOUR_WALLET_ADDRESS",
"HL_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY",
"HL_TESTNET": "true",
"PAPER_TRADING": "true"
}
}
}
}
Restart Claude Desktop. You'll see 🔨 tools available in the input bar.
⚠️ Safety
PAPER_TRADING=true by default. In paper trading mode, all orders are logged but NEVER submitted to Hyperliquid. Safe for testing.
To enable live trading:
- Set
PAPER_TRADING=false - Set
HL_TESTNET=falsefor mainnet - Make sure
HL_PRIVATE_KEYis set - Understand: real money is at risk
The server will always show [PAPER TRADING] or [TESTNET] in tool descriptions so you know which mode you're in.
Never commit your private key. .env is in .gitignore by default.
💰 Monetization (for the managed version)
| Tier | Price | Features |
|---|---|---|
| Open Source | Free | Self-hosted, all tools |
| Cloud Hosted | $29/mo | We host it, no setup, auto-updates |
| Pro Templates | $97 one-time | Strategy templates + backtesting prompts |
| Custom Bot | $500–$2,000 | Done-for-you custom trading agent |
🗺️ Roadmap
- Historical trade data tool
- Portfolio P&L over time
- Multi-account support
- Telegram bot integration
- Strategy backtesting tool
- Automated rebalancing agent
📄 License
MIT — use it, fork it, build on it.
Built by AgentReady — making businesses and markets AI-agent ready.