market-depth-lab-mcp

# Market Depth Lab MCP

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

🌐 **Project website and live dashboards: [marketdepthlab.com](https://marketdepthlab.com)**

Every MCP result points back to **[Market Depth Lab](https://marketdepthlab.com)**,
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](https://marketdepthlab.com).

## Tools

| Tool | What it answers |
| --- | --- |
| `list_active_hyperliquid_twaps` | Which public TWAP schedules are active, and what is their estimated current notional? |
| `analyze_hyperliquid_wallet` | What positions, balances, orders, leverage and PnL are visible for this public address? |
| `calculate_hyperliquid_fees` | What would the estimated fee be for this notional, role and fee tier? |
| `get_hype_market_snapshot` | What is HYPE worth now, and how do spot and perps compare? |
| `hyperliquid_summarize_large_trader_positions` | How is the monitored large-trader cohort positioned by market? |
| `hyperliquid_list_top_position_holders` | Which monitored addresses have the largest positions in one market? |
| `hyperliquid_list_funding_rates` | Who pays funding now, and what is the exact trailing-24h sum for the returned markets? |
| `scan_cross_exchange_funding_spreads` | Where is the largest normalized funding difference across Binance USD-M, OKX and Hyperliquid, after a user-supplied cost estimate? |
| `scan_cross_exchange_perp_price_spreads` | Where 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`](https://www.npmjs.com/package/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.git
cd market-depth-lab-mcp
npm ci
npm 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. Show
the current annualized spread, projected net carry and break-even hours.
```

```text
Scan BTC, ETH and SOL perpetual top-of-book spreads across Binance, OKX and
Hyperliquid. Use round-trip taker fees, require at least $5,000 visible at
the 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 longs
from 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

| Capability | Data path |
| --- | --- |
| HYPE, wallet and Hyperliquid funding | Your local MCP process → public Hyperliquid `info` API |
| Cross-exchange funding spreads | Your local MCP process → public Binance USD-M, OKX and Hyperliquid market-data APIs |
| Cross-exchange price spreads | Your local MCP process → public Binance USD-M and OKX book-ticker APIs plus Hyperliquid `l2Book` |
| Active TWAPs | Your local MCP process → public HypurrScan endpoint, plus Hyperliquid price references |
| Large positions and top holders | Your local MCP process → Market Depth Lab's rolling read-only position index |
| Fee calculator | Runs 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.

| Variable | Default | Purpose |
| --- | --- | --- |
| `MDL_POSITION_INDEX_URL` | `https://data.marketdepthlab.com/v1/positions/latest` | Remote read-only position index |
| `MDL_POSITION_INDEX_PATH` | unset | Load a local JSON snapshot instead of the remote index |
| `MDL_MAX_SNAPSHOT_AGE_HOURS` | `24` | Mark a position snapshot stale after this age |
| `MDL_REJECT_STALE` | `false` | Return an error instead of labeled stale data |
| `MDL_HTTP_TIMEOUT_MS` | `15000` | Per-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 ci
npm run check
npm test
npm 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

- Website: [https://marketdepthlab.com](https://marketdepthlab.com)
- Live tools: [https://marketdepthlab.com](https://marketdepthlab.com)
- Issues: [GitHub Issues](https://github.com/derkcc/market-depth-lab-mcp/issues)
- Security: [SECURITY.md](./SECURITY.md)
- Contributing: [CONTRIBUTING.md](./CONTRIBUTING.md)

## License

[MIT](./LICENSE)