@ironflowsh/mcp

MCP server for Ironflow, the agent cloud for Hyperliquid: market data, wallet analytics and liquidation alerts for Claude, Cursor and any MCP client. It covers native perps, HIP-3 builder markets, HIP-4 outcome markets and spot. 50 tools: 42 read data, including run_query for read-only SQL over every Hyperliquid fill, wallet, funding and liquidation table, 4 manage liquidation alerts that Ironflow posts to your Discord, Slack, Telegram or webhook, and 4 spin up and manage Ironboxes.

To run your agent next to Hyperliquid, spin up an Ironbox: a secure sandbox with this data built in.

No API key needed to start: keyless calls get 30 requests per minute, 300 per day and 24 hours of history. A free key from ironflow.sh/key raises that to 60 requests per minute and 14 days. Agents with a USDC wallet on Base can also pay per call with x402, from $0.001 and with no key (pay per call).

Install

The hosted server needs no install and no key: https://mcp.ironflow.sh/mcp (Streamable HTTP).

Claude Code

claude mcp add --transport http ironflow https://mcp.ironflow.sh/mcp

Claude (claude.ai and Claude Desktop): open Customize → Connectors, click Add custom connector, enter the name Ironflow and the URL https://mcp.ironflow.sh/mcp, then click Add. On Team and Enterprise plans an Owner adds it under Organization settings → Connectors → Add → Custom, and members then click Connect.

Cursor: the button above, or add this to ~/.cursor/mcp.json (or a project's .cursor/mcp.json):

{
  "mcpServers": {
    "ironflow": { "url": "https://mcp.ironflow.sh/mcp" }
  }
}

VS Code: the button above, or

code --add-mcp '{"name":"ironflow","type":"http","url":"https://mcp.ironflow.sh/mcp"}'

Local server (stdio): npx -y @ironflowsh/mcp, see Local server.

With a free key

Send it as Authorization: Bearer if_your_api_key, or as ?key=if_your_api_key on the URL for clients that cannot set headers.

claude mcp add --transport http ironflow https://mcp.ironflow.sh/mcp \
  --header "Authorization: Bearer if_your_api_key"

In Cursor, add "headers": { "Authorization": "Bearer if_your_api_key" } next to url.

Local server

npx -y @ironflowsh/mcp

Requires Node.js 18+. Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%/Claude/claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "ironflow": {
      "command": "npx",
      "args": ["-y", "@ironflowsh/mcp"],
      "env": { "IRONFLOW_API_KEY": "if_your_api_key" }
    }
  }
}

The env block is optional. Claude Code: claude mcp add ironflow -- npx -y @ironflowsh/mcp.

To host the HTTP server yourself: npx -y -p @ironflowsh/mcp ironflow-mcp-http (listens on PORT, default 8080, path /mcp).

Tools

Ask anything (SQL): describe_data lists the queryable tables, columns and example queries; run_query runs one read-only ClickHouse SELECT over them (every fill, per-wallet daily totals, behaviour labels, funding, mark and oracle prices, open interest, liquidations, builder-code fills, transfers, vault flows); get_wallet_behavior returns 30-day trading-style labels per wallet. Keyless queries see the last 24 hours; a free key sees 14 days.

Market data: get_price, get_recent_trades, get_candles, get_funding_rates, get_open_interest, get_open_interest_changes, get_premium, get_outcome_markets, get_liquidations, get_liquidation_summary, get_auto_deleveraging, get_fills, get_mark_prices, get_vault_operations, list_markets, get_markets_snapshot

Market analytics: get_funding_stats, get_pnl_leaderboard, get_market_top_wallets, get_wallet_labels, get_vault_leaderboard, get_liquidation_levels (past liquidations by price; a 10-level sample without a key, every level with a free one) and get_liquidation_map (where open positions would be liquidated if the price moved, from every open position on our node)

Signals: get_top_traders, get_market_leaders, get_early_movers, get_trader_profile

Wallet analytics: get_user_state, get_positions_at, get_user_summary, get_user_pnl_series, get_user_funding, get_user_maker_taker, get_user_ledger

Cohorts: list_cohorts, get_cohort_addresses

Status: get_status, get_status_metrics, get_status_history

Liquidation alerts (need an API key; a free key allows one): create_liquidation_alert has Ironflow post matching liquidations to a Discord channel, Slack channel, Telegram chat or HTTPS webhook within seconds, filtered by market, side, size and wallet, and keeps posting after the conversation ends; list_liquidation_alerts, test_liquidation_alert and delete_liquidation_alert manage them. Guide: docs.ironflow.sh/guides/liquidation-alerts.

Ironbox: create_ironbox spins up a secure sandbox next to Hyperliquid for an agent to run and trade in. With no key it makes a 24-hour trial paper box; a free key keeps a box. start_box_strategy, list_box_strategies, stop_box_strategy and get_box_activity run breakout, grid and DCA strategies on a paper box with no client connected, and need only its URL. list_ironboxes, get_ironbox and delete_ironbox need a key. https://mcp.ironflow.sh/mcp?toolset=data serves every tool except these.

Markets can be given as display symbols (BTC-PERP, xyz:NVDA-PERP, HYPE/USDC) or Hyperliquid names (BTC, @107, xyz:NVDA), and times as Unix ms, Unix seconds, ISO 8601 or relative to now (-7d, -24h, now). When the API reads a name, or serves a window that starts later than asked because of the key's history limit, the result starts with a notice saying so. Fill history covers a rolling 12 months. There is no order book, order status or streaming tool; for live feeds the REST API has /v1/liquidations/stream and /v1/trades/stream (Server-Sent Events).

Configuration

Env var	Default
`IRONFLOW_API_KEY`	optional; free key at ironflow.sh/key
`IRONFLOW_API_URL`	`https://api.ironflow.sh`
`PORT` (HTTP server)	`8080`
`MCP_LOG_SALT` (HTTP server)	random per process; keys the caller hash in the access log

Usage data

Each API call carries two headers so we can see which apps and tools people use: X-Ironflow-Client (the MCP client's name and version, e.g. claude-code/2.1.0) and X-Ironflow-Tool (the tool name). The hosted server logs each request's method, tool arguments, client name, status, whether the tool returned an error, the API status and error code behind it, and a salted hash of the caller's IP. It also tells the API about each initialize and tools/list (the client name and version, and whether a key was set, not the key), so sessions are counted next to tool calls. It never logs IPs or API keys.

License

MIT

hyperliquid

Documentation