cryptodata-mcp

Production-ready Model Context Protocol (MCP) server delivering specialized crypto market microstructure, derivatives, order flow CVD/OI regime classification, fear & greed sentiment, and whale tracking context.

Designed specifically to complement charting tools (like TradingView) with real-time data that traditional charts cannot offer.

---

Features & Tools

Tool	Parameters	Description
get_orderflow_and_cvd_context	ticker (required, e.g. "BTC"), period ("15m" | "1h" | "4h" | "1d", default "4h")	Evaluates market conditions against the 9-State Order Flow Matrix using live Price, OI, Spot CVD, and Futures CVD deltas. All four legs span the same 10-candle lookback of the requested period.
get_basis	pair (default "BTCUSDT"), contract_type ("PERPETUAL" | "CURRENT_QUARTER" | "NEXT_QUARTER", default "PERPETUAL")	Returns Futures vs. Spot Basis value, Basis %, and Contango / Backwardation / Parity classification. Annualized basis is reported for dated contracts only (scaled by 365/days-to-expiry); it is undefined for perpetuals.
get_funding_rate	ticker (default "BTC")	Returns the current funding rate %, annualized rate %, next settlement time, and trend direction. The settlement interval is read from the venue (8h, 4h, …) rather than assumed.
get_buy_sell_volume_ratio	ticker (default "BTC"), period ("15m" | "1h" | "4h" | "1d", default "4h"), market_type ("spot" | "futures" | "both", default "both")	Taker Buy/Sell volume in USD, Buy/Sell Ratio (> 1.05 = aggressive buyers, < 0.95 = aggressive sellers), Aggressor Delta, and Bias classification.
get_fear_and_greed_index	limit (1-365, default 7)	Global Crypto Fear & Greed Index score (0-100), classification, and multi-day historical trend.
get_whale_and_exchange_flows	ticker (default "BTC"), timeframe ("1h" | "4h" | "12h" | "24h" | "7d" | "1w" | "30d" | "all", default "24h"), min_usd_value (default 1,000,000), max_pages (1-20, default 5), wait_for_login_seconds (0-120, default 3)	Always opens Arkham Explorer — reusing an already-open Arkham window when one is on the debug port, launching one only if not — and scrapes both the Transfers and Trades tabs filtered to the timeframe and USD threshold. Also returns the exchange tape (spot/futures volume over the full timeframe, plus large trades from the recent tape).
open_arkham_whale_tracker	token (required — "BTC", "ETH", "solana"), tab ("transfers" | "trades" | "both", default "both"), timeframe (default "24h"), min_usd_value (default 100,000), max_pages (1-20, default 3), wait_for_login_seconds (0-120, default 3)	Launches Chrome via CDP against https://arkm.com/explorer/token/<token> and scrapes live whale transfers & trades.

Data-availability contract

No tool substitutes placeholder values. When an upstream venue cannot be reached, the tool returns an explicit UNAVAILABLE / INSUFFICIENT DATA result naming the failure, rather than a zero or a default that would be indistinguishable from a real reading. Likewise, a failed Arkham scrape is reported as a scrape failure — never as an absence of whale activity.

---

📊 Order Flow & CVD Cheatsheet Matrix (9 Market Regimes)

The internal matrix evaluator (src/utils/matrixEvaluator.js) classifies live market conditions into one of 9 strategic regimes. CVD is classified as an imbalance ratio against total taker volume (±2% standard, ±8% sharp), so the thresholds carry the same meaning for BTC and for a small cap. A component pointing the opposite way to a regime's specification counts against that regime, and when several regimes score equally the result is reported as AMBIGUOUS rather than silently resolved.

Kondisi Pasar (Market State)	Price	Open Interest (OI)	CVD Spot	CVD Futures	Makna Strategis (Strategic Interpretation)
Healthy Uptrend	Up	Slow Up	Up	Up	Sinyal Beli Terbaik. Uang asli masuk (Spot) dan posisi Long baru dibuka perlahan.
Short Squeeze	Up	Down	Flat	Sharp Up	Kenaikan Semu. Harga meroket karena trader Short dipaksa beli (Buy to Cover) untuk tutup posisi.
Blow-off Top	Up	Sharp Up	Down	Sharp Up	Hati-hati Pucuk. FOMO level akut. Ritel nge-Long agresif, Whale di Spot mulai jualan.
Whale Accumulation	Flat	Slow Up	Up	Flat/Down	Sinyal Emas. Bandar sedang cicil beli (Spot) tanpa membuat harga heboh. Persiapan pump.
Spot Distribution	Flat	Up	Down	Up	Jebakan Bullish. Ritel FOMO nge-Long di pucuk, tapi Whale diam-diam buang barang di Spot.
Market Exhaustion	Flat	Down	Flat	Flat	Konsolidasi / Ragu. Pelaku pasar menutup posisi dan wait and see. Bersiap untuk volatilitas arah baru.
Healthy Downtrend	Down	Slow Up	Down	Down	Trend Turun Valid. Tekanan jual asli dari Spot, diiringi posisi Short baru yang dibangun bertahap.
Long Liquidation	Down	Down	Flat	Down	Pembersihan. Trader Long kena likuidasi berantai. Biasanya akan ada rebound cepat setelah bersih.
Panic Selling / Aggressive Shorting	Down	Up	Down	Sharp Down	Trend Turun Kuat. Investor Spot buang barang dan banyak posisi Short baru dibuka secara agresif.

---

🌐 Arkham Intelligence Whale Tracker Launcher

The server includes an automated browser launcher that opens a dedicated new window of Google Chrome navigating directly to Arkham Token Explorer:

• URL Format: https://arkm.com/explorer/token/<token_name>
• Token slugs are resolved dynamically (BTC -> bitcoin, ETH -> ethereum, SOL -> solana).
• Provides direct tab focus for Transfers and Trades.

Both get_whale_and_exchange_flows and open_arkham_whale_tracker drive this browser. They reuse an already-open arkm.com tab on the debug port when one exists — which is the fast path, and the one that carries your logged-in Arkham session. A browser is launched only when no usable tab is found.

⚠️ A launch opens a visible window using an isolated profile in your temp directory (not your everyday Chrome profile), so you will need to log into Arkham inside it — raise wait_for_login_seconds on that first run. Only a browser this server itself spawned is ever terminated; your own Chrome is left alone.

Coverage caveat: scraping walks max_pages pages per tab from the most recent, and Arkham's own value filter is not driven programmatically. A high min_usd_value on a busy token may therefore return few or no rows simply because the large ones sit deeper than the scanned depth — raise max_pages. The output always states how many pages were scanned, and a failed scrape is reported as a failure rather than as an absence of activity.

The CDP port defaults to 9224 and can be overridden with the ARKHAM_CDP_PORT environment variable.

---

🛠️ Installation & Setup

1. Install

This is plain CommonJS JavaScript — there is no build step.

npm install

2. Register in Cursor (.cursor/mcp.json or .vscode/mcp.json)

Add to your mcp.json:

{
  "mcpServers": {
    "cryptodata-mcp": {
      "command": "node",
      "args": [
        "D:/coding/trading/cryptodata-mcp/src/index.js"
      ]
    }
  }
}

3. Register in Claude Desktop (claude_desktop_config.json)

On Windows, locate %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "cryptodata-mcp": {
      "command": "node",
      "args": [
        "D:/coding/trading/cryptodata-mcp/src/index.js"
      ]
    }
  }
}

---

🧪 Testing Locally

You can run the server directly via node:

npm start

Or connect using the official @modelcontextprotocol/inspector:

npx @modelcontextprotocol/inspector node src/index.js