Content
# Hyperliquid MCP Server
Production-ready **Model Context Protocol (MCP) server** for Hyperliquid, built on the official Hyperliquid Python SDK.
> No UI. No extra glue code. Just a reliable MCP backend you can run locally or in Docker.
---
## Why this project
Hyperliquid automation often fails at the operational layer (setup friction, env drift, brittle startup flows). This repository focuses on **predictable deployment and safe defaults** so you can run agents with confidence.
---
## Feature Overview
- **SDK-native integration** with Hyperliquid (official Python SDK only)
- **Strict input validation** for tool safety and deterministic behavior
- **Standardized response schema** (`ok`, `message`, `data`, structured `error`)
- **Docker-first runtime** with clean startup/stop/reset workflows
- **One-click Windows startup** via `start.bat`
- **Port fallback strategy** for future exposed services (API/UI/metrics)
- **Testnet-first default** to reduce operational risk
---
## Tech Stack
- **Python 3.12+**
- **MCP server runtime** (`mcp`)
- **Hyperliquid official SDK** (`hyperliquid-python-sdk`)
- **Docker + Docker Compose**
---
## Quick Start (Windows - One Click)
1. Install and launch **Docker Desktop**.
2. In this repository root, double-click:
```bat
start.bat
```
What `start.bat` does:
- validates Docker availability and daemon state
- creates `.env` from `.env.example` (if missing)
- checks reserved ports (`APP_PORT`, `METRICS_PORT`)
- auto-switches occupied ports to free fallbacks
- runs `docker compose up --build -d`
- verifies that services are running and prints status
### Stop services
```bat
stop.bat
```
### Full reset (clean state)
```bat
reset.bat
```
---
## Installation (Manual / Cross-Platform)
```bash
cp .env.example .env
# edit .env with your credentials
docker compose up --build -d
```
To stop:
```bash
docker compose stop
```
To reset:
```bash
docker compose down -v --remove-orphans
```
---
## Usage
This server is intended for MCP-compatible clients (e.g., local agent runtimes).
### Example: local Python execution
```bash
python -m hyperliquid_mcp.server
```
### Example MCP config snippet
```json
{
"mcpServers": {
"hyperliquid": {
"command": "python",
"args": ["-m", "hyperliquid_mcp.server"],
"env": {
"HYPERLIQUID_PRIVATE_KEY": "0x...",
"HYPERLIQUID_ACCOUNT_ADDRESS": "0x...",
"HYPERLIQUID_TESTNET": "true"
}
}
}
}
```
---
## Configuration (`.env`)
### Required
- `HYPERLIQUID_PRIVATE_KEY`
### Optional
- `HYPERLIQUID_ACCOUNT_ADDRESS`
- `HYPERLIQUID_VAULT_ADDRESS`
- `HYPERLIQUID_TESTNET` (`true` by default)
- `LOG_LEVEL`
### Reserved Port Variables (Future Services)
- `APP_PORT` (default `18080`)
- `METRICS_PORT` (default `19090`)
The current MCP server communicates over stdio, so no host port mapping is required today. These vars are included to support future HTTP/metrics services without redesigning local workflows.
---
## Docker Usage & Port Fallback Strategy
### Current state
- The main service runs over stdio in Docker.
- No UI assumptions are made.
### Future-ready port strategy
- Define all host ports in `.env` (`APP_PORT`, `METRICS_PORT`, etc.).
- In `docker-compose.yml`, always reference env vars (`${APP_PORT}`) for mappings.
- `start.bat` checks whether reserved ports are already occupied.
- If occupied, it increments to the next free port (up to 10 attempts).
- If no free port is found, it exits with an actionable error.
### Extending with a future API/UI service
Use compose mappings like:
```yaml
ports:
- "127.0.0.1:${APP_PORT:-18080}:8080"
- "127.0.0.1:${METRICS_PORT:-19090}:9090"
```
This keeps startup stable across different local environments and prevents silent port conflicts.
---
## Troubleshooting
### Docker not running
- Start Docker Desktop and wait until it reports healthy.
- Re-run `start.bat`.
### Startup fails after compose build
- Check service state:
```bash
docker compose ps
```
- Check logs:
```bash
docker compose logs --tail=100
```
### Credentials/config errors
- Ensure `.env` exists and contains a valid `HYPERLIQUID_PRIVATE_KEY`.
- Keep `HYPERLIQUID_TESTNET=true` unless you explicitly need mainnet.
### Need a clean environment
- Run:
```bat
reset.bat
```
- This removes containers, volumes, and orphans.
---
## Security & Operational Notes
- Never commit `.env` or private keys.
- Use dedicated automation wallets.
- Prefer testnet during development.
- Switch to mainnet only after validating tooling behavior.
---
## Roadmap (Optional)
- [ ] Optional HTTP bridge profile for non-stdio clients
- [ ] Healthcheck/metrics endpoint profile
- [ ] CI job for Docker compose smoke test
- [ ] Versioned release workflow for public distribution
---
## License
MIT (see `LICENSE`).
