@blackforge-so/mcp

A Model Context Protocol stdio server that puts BlackForge market data in your agent's hands: real time crypto market data from the major exchanges (binance, bitget, bybit, coinbase, gate, kraken, kucoin, mexc, okx), 150+ metrics for 14,000+ pairs, per pair per closed minute (1m on Ultra and PAYG; 5m, 1h and 1d rollups for every plan). It also reads the linear futures contracts on the major futures venues: funding, open interest, prices, taker flow and liquidations (Futures).

Every column is a measurement with a definition: order book depth and shape, resting liquidity lifetimes, trade-explained vs book-implied volume, spreads and market-wide context, returned in context so an agent can read the raw microstructure directly. It is a thin client over the public BlackForge /v1 API; it stores nothing and re-shapes nothing.

Quickstart

Add the server to your MCP client and paste an API key. Claude Desktop (claude_desktop_config.json) or Claude Code (.mcp.json):

{
  "mcpServers": {
    "blackforge": {
      "command": "npx",
      "args": ["-y", "@blackforge-so/mcp"],
      "env": { "BLACKFORGE_API_KEY": "bf_live_your_key" }
    }
  }
}

No install step: npx -y @blackforge-so/mcp fetches and runs the server on demand.

Where to get a key

Mint a key at app.blackforge.so → API. The server never creates keys; it reads BLACKFORGE_API_KEY from its environment. The blackforge_catalog tool works without a key, so you can verify the install before pasting one.

Related MCP server: iturri

Tools

Plan entitlements (which venues, columns, and intervals a key may read) are enforced by the API. When a column is dropped because your plan does not include it, the tool result reports it in columnsOmitted so the agent understands why a key is absent. Venue- or interval-level restrictions come back as a clear tool error carrying the HTTP status and the server's message (including the upgrade URL, verbatim).

Futures

The same key reads the linear futures contracts (perpetual and dated) on the major futures venues, in real time: mark, index, last and best bid and ask prices, the funding rate and next funding time, open interest in coins and in quote currency, taker buy and total volume, and liquidations. History is kept like spot, from 7 November 2026: each plan reads futures through its usual history window. The futures block of blackforge_catalog lists the futures venues (with whether each publishes a liquidation feed), every futures column, its own quality-flag table and when the history starts.

Plans follow the spot ladder: Free reads binance, gate and mexc futures as daily bars over the last 14 days; Pro adds every futures venue at 1h; Max goes down to 5m and adds the liquidation columns and the event feed; Ultra and PAYG go down to 1m. A funding rate is per the venue's own funding interval, which differs between venues. Liquidations come from each venue's public feed: some venues throttle it (a lower bound in a cascade) and some publish none (null); the catalog says which.

Live formulas and the live order book

Beyond the stored history, the server reaches BlackForge's realtime host. Write your own measure from order book and trade data across the major venues, stream it every second, and get notified when it crosses a value you choose.

A formula looks like mid(binance:BTCUSDT) - mid(okx:BTC-USDT) or buyVol(binance:SOLUSDT, 60s) / max(sellVol(binance:SOLUSDT, 60s), 1). Pairs are spelled exactly as blackforge_symbols lists them. The full function list is in the blackforge_formula_validate tool description. Streaming and notifications are charged one row per referenced pair per evaluation; live book reads by levels returned or walked, against the same monthly quota as everything else. Every streamed value carries flags (for example WARMING while a windowed term has not filled its window yet) and null means there was no number, never zero.

The stream uses Node's built-in WebSocket, so blackforge_formula_watch needs Node 22 or newer; every other tool runs on Node 20. Your key travels in the x-api-key header, never in a URL.

Charts

blackforge_series and blackforge_futures_series also ship an interactive chart. A host that implements the MCP Apps extension (io.modelcontextprotocol/ui) renders the result as a line chart with flagged buckets drawn in the same convention the BlackForge console uses; every other host sees exactly the JSON it saw before.

Nothing about the tool contract changes. The chart payload travels in the result's _meta, which is protocol metadata and reaches no model, so content[0].text is byte-identical whether or not your host renders widgets, so the token cost of a series is the same either way. That is deliberate: structuredContent would have been the obvious home for it, but core MCP treats that field as server-produced result data, and a host without Apps support may hand it to the model, doubling the cost of a large series.

The chart is one self-contained HTML file with uPlot and all CSS inlined, because MCP Apps render under a deny-by-default CSP where an external <script> would simply never load. It is read-only and never calls back into the server: it draws the points it was given and cannot spend your row quota behind your back. Series longer than 2,000 points are decimated for the chart only (the tool still returns every point), and the payload says so rather than quietly thinning the line.

Data quality

When the API reports a row's measurement quality, blackforge_latest carries it through as a quality object (flags naming what went wrong in the window, contaminates listing which figures it flags) plus a plain-English qualityNote. blackforge_series aggregates it into one qualitySummary ({ flaggedBuckets, of, flags }) rather than repeating it on every point. Both keys are omitted entirely when nothing is flagged, and a quality.raw of 32768 means the row predates the quality rail and was never assessed: unknown, not bad. The flag decode table lives on the qualityFlags metric in blackforge_catalog, as a bits array; this server reads it from there and never carries a copy of its own.

Configuration

Local development

npm install
npm run build     # → dist/index.js (ESM, executable) + dist/widget/chart.html
npm test          # client unit tests + a stdio integration test

build runs tsup first and the widget's vite build second, and the order is load-bearing: tsup's clean wipes the whole of dist/, so reversing them deletes the widget and leaves the server serving a resource that is not there.

The integration test spawns the built server over stdio and drives it with the MCP client. Its data assertions need a local BlackForge API at http://localhost:3001/api; without one, those assertions are skipped and the tool-listing checks still run.

License

MIT