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

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.

Liquidation output is explicitly a short live observation window, not a complete historical liquidation total. A zero is reported only when at least one stream connected and emitted no matching event during that stated sample; if no stream connects, the liquidation leg is UNAVAILABLE.

Local signal history

get_market_intelligence_report appends compact JSONL snapshots to data/market-intelligence.jsonl by default. The file is local, ignored by Git, and can be moved by setting CRYPTODATA_HISTORY_PATH. Call get_signal_performance later to add a fresh price checkpoint and evaluate matured signals at a configurable forward horizon.

The performance report is observational: it depends on when MCP tools were called, and sparse calls may leave signals pending or produce delayed checkpoints. It is not presented as a backtest over continuous exchange candles.

Related MCP server: BRS Signals MCP Server

📊 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.

🌐 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 contract: every requested tab is reset to page 1. The scanner continues until it proves the requested timeframe is covered or reaches Arkham's final page. max_pages and max_duration_seconds are safety ceilings; if either is reached, the result is explicitly PARTIAL and includes each tab's start page, last page, total known pages, native-filter status, and stop reason. A structural parser mismatch is a scrape failure, never evidence of quiet whale activity.

The normal report contains only a small preview so it stays usable in an AI context window. The complete captured arrays are saved locally under data/whale-scans/ and the report returns a scan_id. Call get_whale_scan_rows separately for transfers and trades, following next_cursor until null. This separates browser scan time from model context size: the scraper can capture hundreds of rows without forcing all of them into one response.

Arkham Trades may show both counterparties of one matched execution. The server pairs mirrored BUY/SELL rows and counts their notional once; SIDE is reported descriptively and is not presented as long/short positioning without aggressor or position semantics. Likewise, sampled Binance spot trades are reported as taker-buy/taker-sell flow, never as deposits or withdrawals. Rows whose timestamps cannot be parsed are excluded from finite-timeframe totals and retained in the *_unknown_age cursor tables.

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

Run the deterministic unit tests with:

npm test