Market Data MCP

A multi-asset, real-time market-data platform served over MCP: stocks & ETFs (AAPL, SPY, GLD) and crypto through one set of analysis tools, combining REST snapshots with live WebSocket ingestion — streaming trades and NBBO quotes feed an in-memory tape store, and each equity print is classified buyer- vs seller-initiated via Lee–Ready (1991) against the prevailing NBBO, producing order-flow analytics (CVD, taker ratio) that bar data alone cannot provide.

1. MCP server — mcp_server.py exposes ~18 analysis tools an LLM (Claude Desktop /

Claude Code) calls on demand: OHLCV, indicators, trend regime, order flow, VWAP/ATR, volume profile, signal confluence. Tool responses are always aggregates — raw ticks never cross the tool boundary, so streaming adds zero token overhead.

1. CLI — FetchKlines.py writes a compact multi-timeframe text snapshot to disk.

Equities stream from Alpaca (trades + NBBO quotes over WebSocket; bars over REST) and need a free API key — see Multi-asset. Additional venue adapters cover crypto keylessly (Binance, Bybit, Hyperliquid, Coinbase, CoinGecko), including perp derivatives context (funding, open interest, basis). Commodity futures are not covered (use ETF proxies like GLD/USO).

Architecture

Layered so dependencies point downward only — I/O ↘ orchestration ↘ math/presentation ↘ tools:

Stream data flow: streams/* → store.py (classify + buffer) → mcp_server.py (aggregate out). The REST path stays as the cold path — every tool answers on first call, and the stream upgrades data quality (trade-level flow, live quotes) once warm.

Setup

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Multi-asset (stocks & ETFs)

Crypto works out of the box (keyless). To pull stocks/ETFs (e.g. AAPL, SPY, GLD), set Alpaca credentials in your environment (never commit them):

export APCA_API_KEY_ID=your_key
export APCA_API_SECRET_KEY=your_secret
export ALPACA_FEED=iex      # default; set 'sip' if you have the paid full-tape subscription

• Routing is automatic: a USDT-suffixed symbol (BTCUSDT) → crypto; anything else

(AAPL) → equity via Alpaca. Every price tool also takes asset_class="crypto"|"equity" to force it.

• Equity-capable tools: get_klines, get_indicators, get_emas, get_vwap, get_atr,

get_volume_profile, get_squeeze, get_regime, get_patterns, get_correlation (reference defaults to SPY for equities), get_confluence (equities skip the derivatives votes), and — via the WebSocket stream — get_cvd (live Lee–Ready-classified order flow) and get_orderbook (live NBBO top-of-book). Stream tools subscribe lazily on first call ("warming") and need an open US market to tick.

• Crypto-only tools (return a clean N/A for equities): get_futures_context,

get_funding, get_volume_breakdown, get_market_breadth.

• IEX feed caveat: the free Alpaca feed reports only IEX volume (~2–3% of the tape), so

volume-based fields (volume profile/ratio/OBV, streamed CVD magnitude) are flagged low-confidence for equities; price tools are unaffected. Set ALPACA_FEED=sip for the full consolidated tape.

• Not available for equities: L2 order-book depth (NBBO top-of-book only) and commodity

futures (use ETF proxies like GLD/USO).

CLI usage

.venv/bin/python FetchKlines.py BTCUSDT      # write a snapshot for BTCUSDT
.venv/bin/python FetchKlines.py ZECUSDT
.venv/bin/python FetchKlines.py --clean      # delete all snapshot .txt files
.venv/bin/python FetchKlines.py --clean BTCUSDT  # delete only BTCUSDT snapshots

Writes a file like BTCUSDT_2026-05-29_1430.txt next to the script.

MCP tools

Each tool returns structured fields plus a summary text block, and returns {"error": "..."} on failure instead of crashing.

symbol is a crypto pair like BTCUSDT, ETHUSDT (quote in USDT) or — for the equity-capable tools — a stock/ETF ticker like AAPL, SPY, GLD (needs Alpaca creds; see Multi-asset).

Try it interactively

.venv/bin/mcp dev mcp_server.py

Opens the MCP Inspector in your browser; call each tool and inspect the responses.

Use with Claude Desktop

1. Open Claude Desktop → Settings → Developer → Edit Config. This opens

claude_desktop_config.json (on macOS it lives at ~/Library/Application Support/Claude/claude_desktop_config.json).

1. Add this server under mcpServers (use absolute paths):

   {
     "mcpServers": {
       "market-data-mcp": {
         "command": "/absolute/path/to/binancedatapuller/.venv/bin/python",
         "args": ["/absolute/path/to/binancedatapuller/mcp_server.py"]
       }
     }
   }

If the file already has other servers, add "market-data-mcp" as another key inside the existing mcpServers object rather than replacing it.

1. Fully quit and reopen Claude Desktop (the config is read on startup).

1. The tools appear under the tools/plug icon in the chat input. Then just ask, e.g.:

• "Check the funding rate and order-book imbalance for ETHUSDT."
• "Pull 4h candles and the ADX for BTCUSDT and tell me the trend."

Claude calls the relevant tools and reasons over the fresh data it gets back.

Use with Claude Code (alternative)

claude mcp add market-data-mcp -- \
  /absolute/path/to/binancedatapuller/.venv/bin/python \
  /absolute/path/to/binancedatapuller/mcp_server.py

Notes

• Two data paths: REST is fetched on demand per tool call (the cold path — every tool

answers immediately); the WebSocket tape is a hot path that warms on first use and upgrades flow tools to trade-level data. Raw ticks stay inside the process — tools return aggregates only, so streaming adds no LLM token overhead.

• Stream connections auto-reconnect with exponential backoff and resubscribe; a symbol's

subscription is LRU-evicted past the per-venue budget.

• The perp trade tape streams from Bybit rather than Binance futures: Binance's fstream

data plane is silently filtered on some networks (handshake succeeds, no frames), and the aggressor-flow signal is equivalent.

• The spot trade tape is venue-routed per symbol: Binance, falling back to Bybit spot,

then Hyperliquid spot for coins Binance doesn't list (probed over REST; successful routes cached, failed probes retried) — so Binance-unlisted coins still get a true trade-level spot CVD read.

• The most recent candle may be in progress (incomplete), same as the raw exchange data.
• Binance public endpoints are rate-limited; on-demand tool calls stay well within limits.
• Crypto data is from keyless public APIs. Two signal classes remain out of scope:
• Liquidations — not exposed by keyless public REST; now feasible via the stream layer

(Bybit publishes liquidations over WebSocket) — see roadmap. Cascade risk is meanwhile readable from the OI quadrant, funding extremes, and ATR.

• On-chain flows (exchange netflows, stablecoin/whale activity) — require a paid/keyed

provider (Glassnode/CryptoQuant/Nansen) with no price-derivable proxy.

Roadmap

• L2 order-book replica for crypto via the exchange diff-depth protocol (snapshot +

buffered-delta sync) — true depth dynamics instead of REST snapshots.

• Liquidation stream (Bybit WS allLiquidation) as volatility/cascade context.
• Market-calendar awareness — distinguish "market closed" from "stream stale" for

equities (currently reported via data_age_s).

• Signal-calibration harness — persist tool verdicts (confluence, regime, pattern

confirmations) and score them against forward returns to tune thresholds on data.