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:

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

stop.bat

Full reset (clean state)

reset.bat

---

Installation (Manual / Cross-Platform)

cp .env.example .env
# edit .env with your credentials

docker compose up --build -d

To stop:

docker compose stop

To reset:

docker compose down -v --remove-orphans

---

Usage

This server is intended for MCP-compatible clients (e.g., local agent runtimes).

Example: local Python execution

python -m hyperliquid_mcp.server

Example MCP config snippet

{
  "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:

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:

  docker compose ps

• Check logs:

  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:

  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).