@missionsquad/mcp-hyperliquid-pro

Read-only MCP server for the Hyperliquid exchange (perps, spot, HIP-3/HIP-4, staking, vaults, HyperEVM, builder fills), built for the Mission Squad platform on @missionsquad/fastmcp.

Status: implemented. 50 read-only tools across 11 domains. No signed/trading actions. The public Hyperliquid API needs no auth, so the server starts with no secrets; one optional CoinGecko key is read from the platform's hidden-secret channel.

Requirements

• Node.js >=20
• Yarn

Install & run

yarn install --frozen-lockfile
yarn build
yarn start          # serves over stdio

After publish it is also available as the mcp-hyperliquid-pro CLI.

Tool surface (50 tools, all hl_-prefixed, all read-only)

Domain	Tools
Perp/spot market	hl_get_meta, hl_get_meta_and_asset_ctxs, hl_get_all_mids, hl_get_predicted_fundings, hl_get_perps_at_oi_cap, hl_get_l2_book, hl_get_recent_trades, hl_get_candle_snapshot, hl_get_funding_history
Spot	hl_get_spot_meta, hl_get_spot_meta_and_asset_ctxs, hl_get_token_details, hl_get_spot_deploy_state
HIP-3	hl_get_perp_dexs, hl_get_perp_dex_meta, hl_get_perp_deploy_auction_status
HIP-4	hl_get_outcome_meta, hl_get_settled_outcome
Account	hl_get_clearinghouse_state, hl_get_spot_clearinghouse_state, hl_get_open_orders, hl_get_frontend_open_orders, hl_get_user_fills, hl_get_user_fills_by_time, hl_get_user_funding, hl_get_user_ledger_updates*, hl_get_historical_orders, hl_get_user_fees, hl_get_user_rate_limit, hl_get_user_role, hl_get_sub_accounts, hl_get_portfolio, hl_get_referral_state
Staking	hl_get_delegator_summary, hl_get_delegations, hl_get_delegator_rewards, hl_get_validator_summaries
Vaults	hl_get_vault_details, hl_get_user_vault_equities, hl_get_vault_summaries
HyperEVM	hl_evm_block_number, hl_evm_get_block, hl_evm_call, hl_evm_get_logs
Builder fills	hl_get_builder_fills
Computed (derived)	hl_get_market_risk_snapshot, hl_get_oi_ratio
Stream (WS-backed poll)	hl_poll_trades, hl_watch_address, hl_poll_user_events

* auto-paginates past the upstream 500/2000-row cap using the last time as the next startTime.

Every tool returns a JSON Envelope:

{ ok: boolean, data: T | null, source: "info"|"ws"|"evm"|"s3", fetchedAt: number,
  budgetRemaining?: number, error?: { message: string, retryAfterMs?: number } }

User-fixable problems (bad address, current-day builder file, watch-cap exceeded) are returned as MCP errors with a corrective message. Upstream/rate-limit faults are returned as ok:false envelopes; rate limits include retryAfterMs.

Coin identifier convention

• Perp: the name from hl_get_meta (e.g. "BTC").
• Spot: "PURR/USDC" or "@{index}" (e.g. "@107").
• HIP-3 perp: "{dex}:{ASSET}" (e.g. "xyz:TSLA").

Account/vault tools take a visible user/address — public on-chain data, not a secret.

Secrets (hidden-secret injection)

Core tools need no secrets. Optional keys are read per-call from FastMCP context.extraArgs, never from a tool schema and never logged (only the extra-arg key names are logged):

Hidden key	Used by	Required
coingeckoApiKey	hl_get_oi_ratio for assets not listed on Hyperliquid	no
duneApiKey	reserved for ecosystem analytics	no

Local standalone runs may set HL_COINGECKO_API_KEY / HL_DUNE_API_KEY; hidden values always win.

mcp-api registration

{
  "name": "mcp-hyperliquid-pro",
  "transportType": "stdio",
  "command": "node",
  "args": ["/opt/mcp-hyperliquid-pro/dist/index.js"],
  "secretNames": ["coingeckoApiKey", "duneApiKey"],
  "secretFields": [
    {"name":"coingeckoApiKey","label":"CoinGecko API key","description":"Optional. Market cap for assets not listed on Hyperliquid.","required":false,"inputType":"password"},
    {"name":"duneApiKey","label":"Dune API key","description":"Optional. Ecosystem analytics queries.","required":false,"inputType":"password"}
  ],
  "enabled": true
}

Environment overrides (optional)

HL_INFO_URL, HL_WS_URL, HL_EVM_URL, HL_BUILDER_BASE, HL_COINGECKO_BASE (for testnet/local proxies); HL_COINGECKO_API_KEY, HL_DUNE_API_KEY (local secret fallback).

Scripts

• yarn build — clean + compile (strict, emits .d.ts) + chmod the CLI
• yarn start — run the built server
• yarn test — run the vitest suite (offline; all I/O mocked)
• yarn inspect — FastMCP inspector
• yarn format / yarn format:write — Prettier

Implementation notes & honest gaps

• No tool annotations/outputSchema/structuredContent. @missionsquad/fastmcp@1.1.3's Tool type supports only {name, description, parameters, execute}; adding those fields breaks the strict build. Read-only intent is documented in each tool description instead, and results are JSON envelopes.
• WebSocket connects lazily (on first hl_poll_trades/hl_watch_address), not at boot — avoids a dead socket when streams are unused. userEvents uses a dedicated socket per watched address (cap 8) so events are unambiguously attributable; trades multiplex on one shared socket. Reconnect uses unref'd exponential backoff.
• hl_get_settled_outcome and userEvents are doc-sourced upstream — verify live before relying on them.
• hl_get_vault_summaries returned [] at API-guide capture (2026-05-30); do not depend on it.
• hl_get_oi_ratio uses native circulatingSupply for HL-listed tokens (no key); CoinGecko enrichment is best-effort via /coins/markets?symbols= and approximate for ambiguous tickers.
• No signing / no trading. place_order and any /exchange action are intentionally absent.

License

MIT