Provides Hyperliquid market data, wallet analytics, and liquidation alerts for AI agents through SQL queries and specialized trading tools.
Also known as ironflowsh/mcp, mcp, @ironflowsh/mcp
- Stars
- 1
- Tools
- 54
- Downloads, 30 days
- 6,816
- Latest version
- 0.20.1
- Last commit
- Nov 15, 2026
- License
- MIT
What is Ironflow MCP?
Ironflow provides Hyperliquid market data, wallet analytics, and liquidation alerts for AI agents through SQL queries and specialized trading tools. It exposes 54 tools, such as get_liquidation_summary, get_liquidations, get_liquidation_map.
Summary generated from the project's README
About Ironflow MCP server
Ironflow provides market data, wallet analytics, and liquidation alerts for the Hyperliquid ecosystem. It is designed for AI agents using clients like Claude, Cursor, or VS Code. The server offers 50 specialized tools, including 42 data-reading tools that allow for complex analysis of native perps, spot, and various builder or outcome markets. Users can execute read-only SQL queries via the run_query tool to access tables containing fills, funding, and liquidations.
Developers can use the hosted HTTP server without an API key, which provides 30 requests per minute and 24 hours of history. Obtaining a free key increases these limits to 60 requests per minute and 14 days of history. For more advanced needs, agents with a USDC wallet on Base can pay per call. The server also supports managing liquidation alerts sent to Discord, Slack, Telegram, or webhooks, and can spin up Ironboxes, which are secure sandboxes for running trading strategies like grid or DCA.
What you can do with it
- 1Execute custom SQL queriesAn AI agent can perform read-only SQL queries over Hyperliquid fill, wallet, and liquidation tables.
- 2Monitor liquidation eventsUsers can set up automated alerts that post liquidation data directly to communication platforms like Slack or Telegram.
- 3Analyze wallet behaviorDevelopers can retrieve specific trading-style labels for a wallet based on its last 30 days of activity.
Written from the project's README. Every use case is checked against a quote from it.
How to install Ironflow MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Ironflow MCP in Claude Code
$ claude mcp add --env 'IRONFLOW_API_KEY=<YOUR_IRONFLOW_API_KEY>' mcp -- npx -y @ironflowsh/mcpInstall Ironflow MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@ironflowsh/mcp"
],
"env": {
"IRONFLOW_API_KEY": "<YOUR_IRONFLOW_API_KEY>"
}
}
}
}Install Ironflow MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@ironflowsh/mcp"
],
"env": {
"IRONFLOW_API_KEY": "<YOUR_IRONFLOW_API_KEY>"
}
}
}
}Install Ironflow MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@ironflowsh/mcp"],"env":{"IRONFLOW_API_KEY":"<YOUR_IRONFLOW_API_KEY>"}}'Install Ironflow MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@ironflowsh/mcp"
],
"env": {
"IRONFLOW_API_KEY": "<YOUR_IRONFLOW_API_KEY>"
}
}
}
}Install Ironflow MCP in Codex
$ codex mcp add mcp --env 'IRONFLOW_API_KEY=<YOUR_IRONFLOW_API_KEY>' -- npx -y @ironflowsh/mcpInstall Ironflow MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] command = "npx" args = ["-y", "@ironflowsh/mcp"] [mcp_servers.mcp.env] IRONFLOW_API_KEY = "<YOUR_IRONFLOW_API_KEY>"
Install Ironflow MCP in Gemini CLI
$ gemini mcp add -s user -e 'IRONFLOW_API_KEY=<YOUR_IRONFLOW_API_KEY>' mcp npx -- -y @ironflowsh/mcpInstall Ironflow MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@ironflowsh/mcp"
],
"env": {
"IRONFLOW_API_KEY": "<YOUR_IRONFLOW_API_KEY>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @ironflowsh/mcp 0.20.1 in an isolated container with no network and no keys. It answered and listed 54 tools.
Ironflow MCP tools 54
Read from the server with tools/listget_liquidation_summaryRead-onlyHow much was liquidated on Hyperliquid, and what were the biggest? Liquidations over a trailing window, totalled across every market or the ones named: count, wallets, notional, longs vs shorts liquidated, the top markets and the largest single liquidation with its price. For the individual liquidations use get_liquidations; for liquidations grouped by price use get_liquidation_levels; for where open positions would be liquidated next use get_liquidation_map. Windows from 15m to 24h without a key, 7d with one.
get_liquidationsRead-onlyWho just got liquidated on a Hyperliquid perp? The latest liquidations of one market from our own nodes, newest first: price, size, side and the liquidated wallet. Hyperliquid's public API has no liquidation feed. For totals and the largest across every market use get_liquidation_summary.
get_liquidation_mapRead-onlyWhere are the liquidation levels on a Hyperliquid perp? Where open positions would be liquidated if the price moved: notional (size x liquidation price) by price range, longs below the current price and shorts above, with running totals from the price outward. Built from every open position in our node's latest snapshot, about every 12 minutes (snapshot.age_s says how old). Cross-margin prices assume the account's other positions stay at mark. For liquidations that already happened use get_liquidation_levels. Without a key you get the 10 largest ranges within 10% of the price; any key, including a free one (https://ironflow.sh/key), returns every range.
get_markets_snapshotRead-onlyWhat is moving on Hyperliquid right now? Active markets ranked in one call: mark price, 24h change, 24h volume, open interest and current hourly funding. Sort by abs_funding for the most extreme funding, abs_change_24h for the biggest movers, or volume (default). Use min_volume_usd to skip illiquid markets.
get_priceRead-onlyWhat is X trading at on Hyperliquid? The latest mark price of one market as a single number: native perps, HIP-3 builder perps (e.g. xyz:NVDA-PERP) and spot. For the oracle price and funding use get_mark_prices; for price history use get_candles; to compare many markets at once use get_markets_snapshot.
get_candlesRead-onlyHow has a Hyperliquid market's price moved? OHLCV candles of one market, built from every trade: open, high, low, close, volume and trade count per candle, oldest first. For only the current price use get_price; for individual trades use get_recent_trades.
get_funding_ratesRead-onlyWhat has funding been on a Hyperliquid perp? Hourly funding rate history, newest first, including HIP-3 builder perps. A positive rate means longs pay shorts. For the rate right now use get_mark_prices; for averages and annualized rates, get_funding_stats.
get_open_interest_changesRead-onlyWhere is money flowing in or out on Hyperliquid? Perps ranked by how their open interest moved over the last 1h, 4h, 24h or 7d: open interest at the start and now (in coins), the change in USD at the latest mark and in percent. For one market's latest open interest use get_open_interest.
get_user_stateRead-onlyWhat positions does a Hyperliquid wallet have open? Its positions right now across native and HIP-3 perps: size, entry and mark price, leverage and unrealized PnL. Use it for 'is this wallet long or short?'. For PnL over time use get_user_pnl_series; for its trading record, get_trader_profile.
get_user_pnl_seriesRead-onlyHow has a Hyperliquid wallet's PnL gone over time? Its realized PnL over time: buckets with realized PnL and fees paid in each, by default daily over the last 30 days. Add the buckets up for a running PnL curve. Realized only: unrealized PnL on open positions is in get_user_state. For totals over a range use get_user_summary.
get_user_fundingRead-onlyHow much funding did a Hyperliquid wallet pay or receive? Per market per bucket: Hyperliquid's own ledger, every hourly payment back to September 2025 (Hyperliquid's API returns only daily totals that far back). Positive means received, negative means paid. bucket=1d gives daily totals, 1h the hourly payments.
get_top_tradersRead-onlyWho are the top traders on Hyperliquid this week or month? Traders ranked across all markets by results over 7, 30 or 90 days: win rate, profit factor, realized PnL, max drawdown and best markets. sort=top ranks by realized PnL, lowrisk by smallest max drawdown, new by most recently first seen. For one market use get_market_leaders.
Show all 54 toolsShow fewer tools
get_market_top_walletsRead-onlyWho trades the most, or makes the most, on one Hyperliquid market? Top wallets there by volume or realized PnL over a window (default the last 24 hours), up to 200 rows.
list_marketsRead-onlyWhat is a Hyperliquid market called? Lists perps (native and HIP-3), spot and live HIP-4 outcomes with symbol, class, issuer, base asset and Hyperliquid coin. Search with q (q=nvda finds xyz:NVDA-PERP and the other NVDA perps).
describe_dataRead-onlyWhat can SQL answer about Hyperliquid? Lists the SQL tables of Ironflow's Hyperliquid data (fills, trades, hourly market totals, wallet daily totals and labels, funding, prices, open interest, liquidations, builder fills, transfers, vault flows), their columns, how far back each goes, query tips, worked examples and your own limits. Call it before run_query. Costs no credits.
run_queryRead-onlyAnything the other tools do not answer: runs one read-only ClickHouse SELECT over Ironflow's Hyperliquid tables (hl.fills, hl.trades, hl.wallet_fills, hl.wallet_daily, hl.wallet_behavior, hl.market_hourly, hl.funding, hl.funding_payments, hl.mark_prices, hl.oracle_prices, hl.open_interest, hl.liquidations, hl.builder_fills, hl.transfers, hl.vault_operations). For volume, taker flow or liquidation totals per market over hours to months read hl.market_hourly, not hl.fills; call describe_data for columns. Aggregate in SQL: results are capped (1,000 rows keyless). Each query costs 10 credits. Keyless: last 24 hours, 5 s per query, 60 query seconds per hour per IP; a free key from https://ironflow.sh/key gives 30 days of history.
get_wallet_behaviorRead-onlyHow does a Hyperliquid wallet trade, and which wallets are whales or market makers? Labels from the last 30 days (market_maker, high_frequency, whale, directional, consistent_winner, big_loser, revenge_sizing, often_liquidated, hip3_trader, spot_trader, prediction_trader) and the numbers behind them (maker share, buy/sell imbalance, fills per day, green-day share, profit factor, liquidations). Look up specific addresses, or list wallets with one label.
get_recent_tradesRead-onlyWhat just traded on a Hyperliquid market? The latest tick-level trades from our own nodes: price, size, side and block time. Covers native perps, HIP-3 builder markets, HIP-4 outcomes and spot.
get_open_interestRead-onlyWhat is open interest on a Hyperliquid perp? The latest open interest of one perp in units of the base asset (BTC for BTC-PERP), with its 24-hour traded volume in USD and the time of the reading. Multiply by get_price for open interest in USD. To compare open interest across markets use get_markets_snapshot; for its history use run_query (see describe_data).
get_outcome_marketsRead-onlyWhat is trading on Hyperliquid's prediction markets? HIP-4 outcome markets (prediction markets on sports, central bank decisions, IPOs and daily BTC price contracts) over the last 4 hours, 1 day or 1 week: traded volume, fills, wallets and active markets, plus the most traded outcomes with their last traded price (the implied probability, 0 to 1) and last-24-hour traded volume. Each outcome has a Yes and a No side whose prices sum to 1. For one outcome's trades or candles pass its symbol to get_recent_trades or get_candles; settled outcomes stay queryable. For per-wallet outcome activity use run_query on hl.wallet_daily with market_class = 'prediction'.
get_premiumRead-onlyHow far does a Hyperliquid perp trade from its oracle? Its mark price against its oracle price over time, with the premium in basis points ((mark / oracle - 1) x 10,000) per bucket and a summary (latest, mean, min, max). On HIP-3 stock, index and commodity perps such as xyz:NVDA-PERP, xyz:GOLD-PERP or xyz:SP500-PERP the oracle follows the underlying, so this shows how far the perp trades from what it tracks, weekends included. Default 1h buckets over the last 7 days. For funding payments use get_funding_rates.
get_auto_deleveragingRead-onlyDid Hyperliquid auto-deleverage anyone? Auto-deleveraging (ADL) fills, newest first, across all markets or one: profitable positions Hyperliquid closed to cover a liquidation its backstop could not absorb. Per fill: wallet, market, side, price, size, notional, realized PnL, trade id (shared with the liquidated side) and transaction hash. Recorded from 2026-08-01; the default window is the last 7 days. For the liquidated side use get_liquidations.
get_fillsRead-onlyWhat did a Hyperliquid wallet trade? Every fill for one wallet, optionally for one market, from indexed history: price, size, side, fee and realized PnL. Hyperliquid's own userFills endpoints stop at the 10,000 most recent fills.
get_mark_pricesRead-onlyWhat is funding on a Hyperliquid perp right now? The latest mark price, oracle price and current hourly funding rate of one perp, with the time of the reading. The funding rate is a fraction per hour (0.0000125 = 0.00125%); positive means longs pay shorts. For only the price use get_price, for funding history get_funding_rates, and for many markets at once get_markets_snapshot.
get_vault_operationsRead-onlyWho moved money in or out of a Hyperliquid vault? Deposits into and withdrawals from one vault or one depositor. Pass vault, address, or both; at least one is required (HLP is 0xdfc24b077bc1425ad1dea75bcb6f8158e10df303).
get_liquidation_levelsRead-onlyAt which prices did liquidations happen on a Hyperliquid perp? Past liquidations bucketed by price and side: where longs and shorts were wiped out (side sell = a liquidated long). For where open positions would be liquidated next, use get_liquidation_map. Without a key you get the 10 busiest levels of the last 24 hours; any key, including a free one (https://ironflow.sh/key), returns every level.
get_vault_leaderboardRead-onlyWhich Hyperliquid vaults are drawing deposits? Vaults ranked by net deposits (deposits minus withdrawals) over the last 7 days, with depositor counts. Keyless calls see the last 24 hours; a free key from https://ironflow.sh/key gives the full 7 days.
get_funding_statsRead-onlyWhat is a Hyperliquid perp's average or annualized funding? Funding statistics per time bucket: average, minimum, maximum and annualized rate.
get_positions_atRead-onlyWhat did a Hyperliquid wallet hold at a past time? Exact perp positions at a past moment, up to 90 days back: market, side, signed size, mark price and notional at that moment, plus today's size and how many fills it made since. Built from Hyperliquid's live positions minus the wallet's fills after that moment, so sizes are exact across native and HIP-3 perps. Needs a free API key; how far back you can go follows the key's history window. For positions right now use get_user_state; for trades in between use get_fills.
get_user_maker_takerRead-onlyIs a Hyperliquid wallet a maker or a taker? Maker vs taker breakdown of its fills per market: volume, fees and rebates. A high maker share with negative maker fees marks a market maker.
get_user_ledgerRead-onlyWhere did a Hyperliquid wallet's money come from or go? Vault deposits, withdrawals and transfers for the wallet, including account deposits and withdrawals and transfers the wallet received. Positive amounts go into the account.
get_pnl_leaderboardRead-onlyWho made or lost the most on Hyperliquid? Every wallet ranked by realized PnL, biggest losses or volume over a window. Wallets with fewer than 5 fills in the window are left out.
get_user_summaryRead-onlyHow much did a Hyperliquid wallet trade or make? Totals over a time range (default the last 24 hours): fill count, volume in USD, realized PnL, fees, wins, losses, win rate and maker versus taker share, plus its current account state (open positions and margin). For a scored record with profit factor, drawdown and a per-market breakdown use get_trader_profile; for PnL over time use get_user_pnl_series.
get_wallet_labelsRead-onlyWhose wallet is this, and who are the whales on Hyperliquid? Labels for notable wallets: top whales by 24h volume, top traders by 30-day realized PnL, vaults and vault leaders. Pass addresses to check specific wallets; without them it lists the whales and smart money.
get_market_leadersRead-onlyWho trades one Hyperliquid market best? The best traders there, ranked by profit factor then win rate, among wallets with at least 5 closed trades there.
get_early_moversRead-onlyWhich wallets trade ahead of the price on a Hyperliquid market? Wallets whose large orders (at least $10k) there tended to come before price moved their way within 30 minutes, over the last 7 or 30 days. Per wallet: scored orders, notional, a lead score (notional-weighted 30-minute move in the order's direction, in basis points), hit rate, last order time and the share cancelled without a fill. At least 5 scored orders per wallet. Check the wallets with get_trader_profile or get_user_state. Past activity does not predict future results.
get_trader_profileRead-onlyIs this Hyperliquid trader any good, and how risky? Its record over 7, 30 or 90 days, rebuilt from its fills: overall win rate, profit factor, trade count, realized PnL and max drawdown; the same numbers per market; its liquidations; and its trades from open to close with direction, timing and peak size. Use it to vet a wallet before following it. For plain totals over any time range use get_user_summary; for positions open right now use get_user_state; for style labels such as market_maker use get_wallet_behavior. A 90d window on a very active wallet can take several seconds.
list_cohortsRead-onlyWhich ready-made Hyperliquid wallet groups are there? Lists address cohorts: six predefined groups (top_pnl_30d, high_volume_30d, whale_fills, net_withdrawers_7d, liquidation_prone, vault_whales) plus any custom cohorts the caller has created
get_cohort_addressesRead-onlyWhich wallets are in a Hyperliquid cohort? Addresses in one named cohort: up to 100, each with the value the cohort ranks by (realized PnL in USD for top_pnl_30d, volume in USD for high_volume_30d), and fetched_at, when the cohort was last computed. Call list_cohorts first for the names and what each one selects. Feed the addresses to get_user_summary, get_trader_profile or get_wallet_behavior to look at each wallet.
get_statusRead-onlyIs Ironflow up? Service status right now: overall state, data freshness per venue and component health.
get_status_metricsRead-onlyHow fast is Ironflow? Performance over rolling windows: API latency and error rate, ingestion lag and synthetic probe timings.
get_status_historyRead-onlyWas Ironflow down? Its own uptime over the last 24 hours (default) or 7 days: points over the period, each with the service status and how fresh the data was in seconds, plus the overall uptime percent. Use it to check whether a gap or odd value in other results came from an Ironflow outage. For the status right now use get_status; for API latency and error rates use get_status_metrics.
create_liquidation_alertActionHave Ironflow post Hyperliquid liquidations to the user's Discord, Slack, Telegram or HTTPS webhook within seconds, filtered by market, side, size and wallet. It keeps running after the conversation: use it when the user wants to be told about liquidations, not just to see them now. Needs an API key (a free key works). Give url (a Discord channel webhook, a Slack incoming webhook or any public https URL) or telegram_chat (then tell the user to add the bot named in the result's setup). A plain webhook gets signed JSON; its signing_secret appears only in this result, so pass it on. Then call test_liquidation_alert.
list_liquidation_alertsRead-onlyNeeds an API key (a free key works). The Hyperliquid liquidation alerts on this API key's account: where each posts (host only), its filter, whether it is active, failed deliveries in a row with the last error, liquidations sent so far, and how many alerts the tier allows. An alert is disabled after 20 failed deliveries in a row; test_liquidation_alert re-enables it once the destination works again.
test_liquidation_alertActionNeeds an API key (a free key works). Send a sample Hyperliquid liquidation, marked as a test, to an alert's destination now and report whether it arrived (delivered true or false, with the destination's answer). A delivered test switches a disabled alert back on. One test per alert every 10 seconds.
delete_liquidation_alertActionNeeds an API key (a free key works). Stop and remove one Hyperliquid liquidation alert from this API key's account; nothing more is sent to its destination.
create_ironboxActionSpin up an Ironbox: a secure sandbox next to Hyperliquid where an agent trades on paper, with Ironflow data, analytics and alerts built in. No key needed: you get a trial box, the agent's own simulated Hyperliquid account for 24 hours, with base_url and expires_at. It ends sooner after 2 hours with no requests and no strategy running. Point the Hyperliquid SDK's base_url at it, or start a strategy on it with start_box_strategy. A free key keeps a box. A paper box never places a real order.
list_ironboxesRead-onlyThe Ironboxes on this API key's account, the sandboxes where agents trade on paper next to Hyperliquid: id, name, state (creating, running, stopped, deleted or error), size, mode, runtime and markets. Without a key there are no saved boxes, and the answer says how to make a trial box with create_ironbox.
get_ironboxRead-onlyNeeds an API key (a free key works). One Ironbox by id: its state (creating, running, stopped, deleted or error), size, mode, runtime, Hyperliquid markets and region.
delete_ironboxActionNeeds an API key (a free key works). Stop and delete one Ironbox from this API key's account; the agent in it stops running on Hyperliquid.
start_box_strategyActionStart a strategy on a Hyperliquid paper box: it runs around the clock with no client connected, in simulation only. No key needed, the box URL authorises it, so a trial box from create_ironbox works. kind is breakout (size_usd, lookback_bars, exit_bars, bar_seconds), grid (lower_px, upper_px, grids, size_usd) or dca (tranche_usd, budget_usd, dip_pct, interval_minutes, take_profit_pct, repeat). Every kind needs market and max_loss_usd: when the net loss reaches it, the strategy closes its position and stops. At most 3 per box, one per market. Follow it with get_box_activity.
list_box_strategiesRead-onlyThe strategies on a Hyperliquid paper box, running and recently stopped, each with its status, stop reason and result. Needs only the box URL.
stop_box_strategyActionStop one strategy on a Hyperliquid paper box: its orders are cancelled and its position is closed at the book, unless close_position is false. The answer says stopping until the close fills, then list_box_strategies shows stopped. Needs only the box URL.
get_box_activityRead-onlyWhat a Hyperliquid paper box and its strategies really did: strategy started, decisions with their reasons, orders, fills, funding, stops, plus equity, PnL, fees and positions. Call it with no after for the latest events, then pass next_cursor as after. gap true means some events were missed. Needs only the box URL.
Configuration
IRONFLOW_API_KEYSecretOptional Ironflow API key. Keyless calls get 30 requests a minute, 100 credits a day and 24 hours of history; a free key from https://ironflow.sh/key gives 60 a minute, 1,000 credits a day (3,000 a month) and 14 days.
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSPass
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHub@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.
Links
- Docs: docs.ironflow.sh
- API reference: docs.ironflow.sh/api-reference
- Hyperliquid node guides: ironflow.sh/guides
License
MIT
Ironflow MCP questions
How do I add Ironflow MCP to Claude Code?
Run claude mcp add --env 'IRONFLOW_API_KEY=<YOUR_IRONFLOW_API_KEY>' mcp -- npx -y @ironflowsh/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Ironflow MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Ironflow MCP provide?
It exposes 54 tools, including get_liquidation_summary, get_liquidations, get_liquidation_map, get_markets_snapshot, get_price.
Do I need an API key to use Ironflow?
No, keyless calls are available with 30 requests per minute, 300 per day, and 24 hours of history. A free key increases these limits.
Can I run SQL queries on Hyperliquid data?
Yes, the run_query tool allows for read-only SQL SELECT queries over tables including fills, wallets, funding, and liquidations.
How can I receive liquidation alerts?
You can manage alerts that post matching liquidations to Discord, Slack, Telegram, or a webhook.