Market Depth Lab

io.github.derkccPublished by GitHub account derkccv0.2.2Updated Oct 24, 2026

Read-only Hyperliquid, funding-rate and cross-exchange perpetual spread tools.

VerifiedSTDIODesktop onlyFinanceData & Analytics

Overview

AI-generated overview

Read-only MCP server giving assistants public Hyperliquid and cross-exchange perpetual market data: funding rates, spreads, wallets, TWAPs and fees.

What you can do
  • Inspect HYPE spot and perp snapshots, Hyperliquid funding rates with trailing 24h sums, and active public TWAP schedules
  • Analyze a public Hyperliquid wallet's positions, balances, orders, leverage and PnL, and estimate fees for a given notional and tier
  • Rank monitored large-trader positions and top position holders in a market, with snapshot time and coverage boundaries
  • Scan cross-exchange funding and perpetual top-of-book price spreads across Binance USD-M, OKX and Hyperliquid, with fee and capacity estimates
When to use it
Useful when you want an assistant to research Hyperliquid and cross-venue perpetual funding or price spreads, check a public wallet's exposure, or estimate trading fees, without any exchange login or trading rights.
Requirements
Runs locally over stdio via npx or a source checkout; needs Node.js 20 or newer and internet access to public Hyperliquid, HypurrScan, Binance USD-M and OKX endpoints. No API key or wallet connection. Optional variables MDL_POSITION_INDEX_URL, MDL_POSITION_INDEX_PATH, MDL_MAX_SNAPSHOT_AGE_HOURS, MDL_REJECT_STALE and MDL_HTTP_TIMEOUT_MS tune the position index and timeouts.
Before you install
Read-only: no order placement, signing or wallet mutation, and no private key or login is requested. A wallet address given to the wallet tool is sent from your machine to the public Hyperliquid API, and position tools query Market Depth Lab's index by default. Spread rows are screening candidates, not proof of executable arbitrage; snapshots are not simultaneous and settlement currencies differ. Research information only, not financial advice.

Installation

In SourceWeft

  1. Open Market Depth Lab in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Market Depth Lab MCP

Read-only Hyperliquid and cross-exchange market research for AI agents.

🌐 Project website and live dashboards: marketdepthlab.com

Every MCP result points back to Market Depth Lab, where the public dashboards, methodology and related research live.

Market Depth Lab MCP gives Claude, Codex, Cursor and other MCP clients nine structured tools for public Hyperliquid and cross-exchange market data. It does not request a private key, wallet signature, exchange login or permission to trade.

Independent open-source software. Not affiliated with or endorsed by Hyperliquid. Research information only; not financial advice.

Why this server

  • Useful on the first call: live HYPE, funding, wallet, TWAP and cross-exchange spread queries.
  • Read-only by design: no order placement, signing or wallet mutation.
  • Honest coverage: monitored-address rankings are labeled as a cohort, not a protocol-wide holder census.
  • Agent-friendly output: each tool returns concise text and stable structuredContent.
  • Traceable: results include source, time/coverage boundaries and one stateful link to the corresponding Market Depth Lab tool.

Tools

ToolWhat it answers
list_active_hyperliquid_twapsWhich public TWAP schedules are active, and what is their estimated current notional?
analyze_hyperliquid_walletWhat positions, balances, orders, leverage and PnL are visible for this public address?
calculate_hyperliquid_feesWhat would the estimated fee be for this notional, role and fee tier?
get_hype_market_snapshotWhat is HYPE worth now, and how do spot and perps compare?
hyperliquid_summarize_large_trader_positionsHow is the monitored large-trader cohort positioned by market?
hyperliquid_list_top_position_holdersWhich monitored addresses have the largest positions in one market?
hyperliquid_list_funding_ratesWho pays funding now, and what is the exact trailing-24h sum for the returned markets?
scan_cross_exchange_funding_spreadsWhere is the largest normalized funding difference across Binance USD-M, OKX and Hyperliquid, after a user-supplied cost estimate?
scan_cross_exchange_perp_price_spreadsWhere do current perpetual best bids and asks diverge across venues, after fee estimates and a visible top-of-book capacity check?

Funding rate and spread engines

The three concepts are deliberately separate:

  1. hyperliquid_list_funding_rates describes the current Hyperliquid main and HIP-3 funding universe, including exact trailing-24h sums for the returned page.
  2. scan_cross_exchange_funding_spreads normalizes one-hour and eight-hour settlement intervals, then compares a lower-funding long leg with a higher-funding short leg. Its annualized number is a comparison, not a forecast.
  3. scan_cross_exchange_perp_price_spreads compares public top-of-book quotes. It reports both entry-fee and round-trip-fee views, plus the smaller visible notional on the selected bid/ask levels. OKX contract counts are converted with the public instrument ctVal before notional is calculated.

The scanners are original TypeScript implementations informed by the read-only monitoring workflow used in Market Depth Lab's local research. They do not vendor or modify the reference Python projects.

Neither scanner places orders. A row is a screening candidate, not proof of executable or risk-free arbitrage. Funding can change; REST snapshots are not simultaneous; Binance/OKX normally settle in USDT while Hyperliquid main perps settle in USDC; and deeper-book slippage, transfers, margin, liquidation, venue access and close-out prices remain outside the estimate.

Requirements

  • Node.js 20 or newer
  • Internet access for public Hyperliquid/HypurrScan data
  • No API key

Install with npm

The public package is market-depth-lab-mcp-server.

Use this configuration in an MCP client that supports local stdio servers:

json
{  "mcpServers": {    "market-depth-lab": {      "command": "npx",      "args": ["-y", "market-depth-lab-mcp-server"]    }  }}

npx downloads the published package and starts the local read-only MCP process. No exchange login, wallet connection or API key is required.

Install from source

bash
git clone https://github.com/derkcc/market-depth-lab-mcp.gitcd market-depth-lab-mcpnpm cinpm run build

Use the absolute path to dist/index.js in your MCP client:

json
{  "mcpServers": {    "market-depth-lab": {      "command": "node",      "args": ["/absolute/path/to/market-depth-lab-mcp/dist/index.js"]    }  }}

Use the source checkout when you want to review or modify the implementation; use the npm configuration above for the shortest installation path.

Example prompts

text
Show the five Hyperliquid markets with the highest absolute current funding.Include trailing 24h funding and explain who pays whom.
text
Compare BTC, ETH, SOL and HYPE funding on Binance, OKX and Hyperliquid.Assume a 24-hour holding period and 12 bps of total round-trip costs. Showthe current annualized spread, projected net carry and break-even hours.
text
Scan BTC, ETH and SOL perpetual top-of-book spreads across Binance, OKX andHyperliquid. Use round-trip taker fees, require at least $5,000 visible atthe selected levels, and explain every non-execution boundary.
text
Analyze 0x... on Hyperliquid. Summarize gross exposure, effective leverage,largest position and recent realized PnL. Do not give trading advice.
text
Within the monitored cohort, list the top BTC positions and separate longsfrom shorts. State the cohort boundary before the ranking.
text
Estimate round-trip taker fees for a $25,000 tier-zero perpetual position.

Data and privacy

CapabilityData path
HYPE, wallet and Hyperliquid fundingYour local MCP process → public Hyperliquid info API
Cross-exchange funding spreadsYour local MCP process → public Binance USD-M, OKX and Hyperliquid market-data APIs
Cross-exchange price spreadsYour local MCP process → public Binance USD-M and OKX book-ticker APIs plus Hyperliquid l2Book
Active TWAPsYour local MCP process → public HypurrScan endpoint, plus Hyperliquid price references
Large positions and top holdersYour local MCP process → Market Depth Lab's rolling read-only position index
Fee calculatorRuns locally; no network request

The server has no analytics or telemetry. A wallet address submitted to analyze_hyperliquid_wallet is sent directly from your machine to the public Hyperliquid API. Position-index calls use https://data.marketdepthlab.com/v1/positions/latest.

Public exchange endpoints can be unavailable in some regions. Both cross-exchange tools expose per-venue available, partial or unavailable coverage and their error messages. They never silently claim that a two-venue or three-venue comparison was complete.

Position-index boundary

Market Depth Lab rotates through a monitored pool of public addresses. The index is useful for cohort-level market structure, but it is:

  • not a list of every Hyperliquid account;
  • not a simultaneous snapshot of all monitored addresses;
  • not proof of who controls an address;
  • not a recommendation to copy any address.

Every position tool reports the snapshot time, age, monitored-address count, staleness state and coverage boundary.

Configuration

All variables are optional.

VariableDefaultPurpose
MDL_POSITION_INDEX_URLhttps://data.marketdepthlab.com/v1/positions/latestRemote read-only position index
MDL_POSITION_INDEX_PATHunsetLoad a local JSON snapshot instead of the remote index
MDL_MAX_SNAPSHOT_AGE_HOURS24Mark a position snapshot stale after this age
MDL_REJECT_STALEfalseReturn an error instead of labeled stale data
MDL_HTTP_TIMEOUT_MS15000Per-request network timeout

When MDL_POSITION_INDEX_PATH is set, the two position tools do not make a network request. Other live-data tools still use public upstream APIs.

Development

bash
npm cinpm run checknpm testnpm pack --dry-run

The test suite performs an in-memory MCP handshake, verifies the nine tool definitions and calls the local fee tool through the protocol. Live upstream smoke tests should be run before each release, but are intentionally excluded from deterministic CI.

Public project links

License

MIT

Source: README.md at commit ad78fbc

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.2LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts