npm package: @hyperliquid-ai/mcp-server
Description: Hyperliquid MCP Server - AI Trading Agent for Claude Desktop
Author: Hyperliquid AI
Latest version: 1.1.1

# @hyperliquid-ai/mcp-server

**Transform Claude Desktop into an AI Trading Powerhouse**

Professional trading signals, technical analysis, and order management directly in Claude Desktop.

## 🚀 Quick Start

### Installation
```bash
npm install -g @hyperliquid-ai/mcp-server
```

### Claude Desktop Setup
```bash
npx @hyperliquid-ai/mcp-server install-claude
```

### Test Your Installation
Open Claude Desktop and ask:
```
"Get BTC trading signal"
```

**That's it!** 🎉

## 🎯 What You Get

- 📈 **Real-time Trading Signals** - AI-powered BUY/SELL/HOLD recommendations
- 📊 **Technical Analysis** - RSI, MACD, Moving Averages, VWAP, Bollinger Bands
- 💼 **Account Management** - Balance, positions, and order tracking  
- 🎯 **Order Placement** - Execute trades directly from Claude (Premium+)
- 📚 **Market Data** - Live prices, orderbooks, and market analysis

## 🔧 Configuration

### Environment Setup
Create `.env` file in your home directory:
```env
# Required: Your Hyperliquid private key
HYPERLIQUID_PRIVATE_KEY=your_private_key_here

# Optional: Main wallet for queries (defaults to trading wallet)
HYPERLIQUID_MAIN_WALLET_ADDRESS=your_main_wallet_address

# Optional: Environment (defaults to testnet)
HL_ENV=mainnet  # or testnet

# Optional: Premium API key for advanced features
HYPERLIQUID_API_KEY=your_premium_api_key
```

### Get Premium API Key
Visit [hyperliquid-ai.xyz](https://hyperliquid-ai.xyz) to:
- 🆓 **Start Free**: 10 requests/hour, basic signals
- 💎 **Premium ($49/month)**: 1,000 requests/hour, all features
- 🏢 **Enterprise ($199/month)**: Unlimited requests, priority support

## 📖 Usage Examples

### Basic Trading Signal
```
Ask Claude: "Get a trading signal for BTC"
```

### Technical Analysis
```
Ask Claude: "Analyze ETH with RSI and MACD on 1h timeframe"
```

### Account Information
```
Ask Claude: "Show my Hyperliquid account balance and positions"
```

### Place Orders (Premium+)
```
Ask Claude: "Place a buy order for 0.1 BTC at market price"
```

## 🛠️ Advanced Configuration

### Manual Claude Desktop Setup
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
```json
{
  "mcpServers": {
    "hyperliquid-ai": {
      "command": "node",
      "args": ["/path/to/@hyperliquid-ai/mcp-server/dist/server.js"]
    }
  }
}
```

### Custom Installation Path
```bash
# Install to specific location
npm install @hyperliquid-ai/mcp-server --prefix /your/custom/path

# Configure Claude Desktop manually
npx @hyperliquid-ai/mcp-server install-claude --path /your/custom/path
```

## 🔍 Available Commands

### CLI Commands
```bash
# Install Claude Desktop configuration
npx @hyperliquid-ai/mcp-server install-claude

# Remove Claude Desktop configuration  
npx @hyperliquid-ai/mcp-server uninstall-claude

# Test MCP server connection
npx @hyperliquid-ai/mcp-server test

# Start server manually (for debugging)
npx @hyperliquid-ai/mcp-server start
```

### MCP Tools Available in Claude
- `get_trading_signal` - Generate AI trading recommendations
- `get_technical_analysis` - Advanced technical indicator analysis
- `get_account_info` - View balance and positions
- `get_market_data` - Real-time prices and market info
- `place_order` - Execute trades (Premium+)
- `cancel_order` - Cancel existing orders (Premium+)
- `get_order_status` - Check order status (Premium+)

## 🚨 Security Best Practices

- ⚠️ **Never share your private key**
- 🔒 **Use environment variables** for sensitive data
- 🧪 **Start with testnet** to learn the system
- 💡 **Use separate wallet** for trading vs main holdings
- 📱 **Enable 2FA** on your Hyperliquid account

## 🐛 Troubleshooting

### Common Issues

**"HYPERLIQUID_PRIVATE_KEY is required"**
- Set your private key in `.env` file or environment variables

**"Claude Desktop not detecting MCP server"**
- Run `npx @hyperliquid-ai/mcp-server install-claude` again
- Restart Claude Desktop completely
- Check Claude Desktop logs for errors

**"API rate limit exceeded"**
- Upgrade to Premium at [hyperliquid-ai.xyz](https://hyperliquid-ai.xyz)
- Check your API key configuration

### Debug Mode
```bash
# Enable detailed logging
DEBUG=hyperliquid-mcp npx @hyperliquid-ai/mcp-server start
```

## 📚 Documentation

- 🌐 **Dashboard**: [hyperliquid-ai.xyz](https://hyperliquid-ai.xyz)
- 📖 **Full Documentation**: [GitHub Repository](https://github.com/hyperliquid-ai/hyperliquid-ai-mcp)
- 🆘 **Support**: support@hyperliquid-ai.xyz

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🤝 Contributing

Contributions welcome! Please see our [contributing guidelines](https://github.com/hyperliquid-ai/hyperliquid-ai-mcp/blob/main/CONTRIBUTING.md).

---

**Transform your trading with Claude Desktop + Hyperliquid MCP Server** 🎯