candlefeed-mcp

An MCP server that gives Claude Code, Claude Desktop, Cursor or any MCP client the CandleFeed order book files as tools: find a published day, download it with SHA-256 checks, rebuild the Binance USD-M book, and ask for the book, spread or depth at any moment. It also wraps four REST datasets (candles, funding, open interest, liquidations). It runs locally over stdio, and order book files are rebuilt on your machine, not on ours.

The data is historical. Order book days are published the morning after each UTC day ends, and every known gap is listed in the public gap log.

Tools

The four REST tools return rows oldest first. Without a start, they return the newest limit rows (500 by default) up to a fixed end: end, or the moment of the call, sent to the API and enforced on the rows. For candles, open interest and bucketed liquidations the window opens on a bucket boundary limit buckets before the bucket holding the end, so no candle is cut short by the query (the newest one may still be filling); funding reads limit × 8 h back (× 1 h on Hyperliquid) and tick liquidations the last 24 hours. On the Free plan the window starts at the first whole bucket inside the last 30 days. With a start, they return the first limit rows from it. Every result carries window (from, to, and whether it was the default) and a note that says which side truncated cut.

Depth outside the anchor snapshot's known price window is partial. Report completeness per band and exclude incomplete samples from full-depth statistics. l2_depth_summary flags each band and averages complete samples only.

The SHA-256 checks prove the files are consistent with what CandleFeed published for that day. They aren't a signature: hashes delivered by the same service as the files can't detect that service itself being compromised or malicious.

The rebuild follows the published rule (the same code as candlefeed.l2book): anchor on a snapshot that isn't in_gap, apply the event that contains its lastUpdateId whole, and report nothing between a chain break and the next snapshot. A moment with no trustworthy book comes back as an error that says why.

What it costs to use

The 1st of every month is a free sample day on every plan, Free included, for every order book symbol. Sample downloads count against 10 GiB of new files per account per month; downloading the same file again that month is free. Every other day needs the Pro plan ($149/mo). A BTCUSDT book day is about 0.35 GB, so ask for days on purpose. REST tools follow the usual plan limits: Free gets BTC, ETH, SOL, XRP and DOGE on Binance for the last 30 days. Plans: https://candlefeed.ai/pricing?utm_source=mcp&utm_medium=readme

CandleFeed data, including samples, is licensed for internal use under Terms §5.3. Published charts, statistics, and research must not include Raw Data or Substantially Raw Derivatives. The raw files and row-level data aren't to be shared.

Install

Needs Python 3.10+ (CPython) on Linux or macOS. Downloads rely on directory-relative, no-follow file operations to stay inside the cache, and refuse to run where those don't exist (Windows).

pip install candlefeed-mcp      # pulls in candlefeed[l2]>=0.3.6,<0.4
which candlefeed-mcp            # use this absolute path below if your client can't find the command

Get a free key at https://candlefeed.ai/signup?utm_source=mcp&utm_medium=readme&utm_campaign=mcp (Free plan, no card, about a minute). The server reads it from CANDLEFEED_API_KEY in its own environment and never takes it as a tool argument. Tool results and errors, including the SDK's argument errors and any text the API echoes back, are scrubbed of that exact key and of download-link signatures before they're returned.

Claude Code

claude mcp add candlefeed --env CANDLEFEED_API_KEY=cf_live_... -- candlefeed-mcp

Or in .mcp.json at the project root:

{
  "mcpServers": {
    "candlefeed": {
      "command": "candlefeed-mcp",
      "env": { "CANDLEFEED_API_KEY": "cf_live_..." }
    }
  }
}

A full BTC day download can take a minute or more. If a call times out, raise MCP_TOOL_TIMEOUT (milliseconds) before starting claude, and run the download again: files that finished are kept and skipped.

Claude Desktop

Settings, Developer, Edit Config, then add to claude_desktop_config.json:

{
  "mcpServers": {
    "candlefeed": {
      "command": "/absolute/path/to/candlefeed-mcp",
      "env": { "CANDLEFEED_API_KEY": "cf_live_..." }
    }
  }
}

Restart Claude Desktop. It doesn't inherit your shell's PATH, so use the absolute path from which candlefeed-mcp.

Cursor

~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "candlefeed": {
      "command": "candlefeed-mcp",
      "env": { "CANDLEFEED_API_KEY": "cf_live_..." }
    }
  }
}

Settings

Downloaded days sit under <cache>/book/binance/<SYMBOL>/<YYYY-MM-DD>/, the same layout CandleFeed().download_l2 writes, so you can open them with candlefeed.l2book.L2Book.load(<cache>, "BTCUSDT", "2026-09-01") in your own code.

Try it

Download the free BTCUSDT order book sample for 2026-09-01, find the biggest 1-minute move of the day, and show me the spread and the depth within 10 and 50 bps for ten minutes either side of it.

The agent calls l2_download_day, l2_spread_summary (which reports the biggest 1-minute move) and l2_depth_summary with window_minutes=10.

Development

pip install -e "./clients/python[l2,dev]" -e "./integrations/mcp[dev]"
pytest integrations/mcp/tests

Tests mock every HTTP call and build synthetic order book days with a known true book.