Provides real-time crypto market data, including spot order books, futures funding, open interest, and liquidations from major exchanges.
Also known as blackforge-so/mcp, @blackforge-so/mcp
- Stars
- 0
- Tools
- 21
- Downloads, 30 days
- 1,211
- Latest version
- 0.5.0
- Last commit
- Nov 10, 2026
- License
- MIT
What is BlackForge MCP?
BlackForge provides real-time crypto market data, including spot order books, futures funding, open interest, and liquidations from major exchanges. It exposes 21 tools, such as blackforge_catalog, blackforge_symbols, blackforge_latest.
Summary generated from the project's README
About BlackForge MCP server
Accessing real-time cryptocurrency market microstructure from inside an AI agent is what this server enables. It provides developers and traders with over 150 metrics for more than 14,000 trading pairs across major exchanges like Binance, Coinbase, and Kraken. The server acts as a thin client for the BlackForge API, delivering spot data, linear futures contracts, funding rates, open interest, and liquidation events directly to your MCP client.
Users can set up the server via npx in Claude Desktop or Claude Code by providing a BLACKFORGE_API_KEY in the environment variables. While the blackforge_catalog tool works without authentication, most data retrieval requires a valid key. The server supports various data granularities, including one-minute intervals for Ultra and PAYG plans, as well as five-minute, one-hour, and one-day rollups.
Beyond historical and latest data, the server offers advanced features for Ultra plan users, such as creating custom formulas to monitor spreads or volume ratios. It also provides access to live order books and real-time streaming via WebSockets. For those using compatible hosts, time series data can be rendered as interactive line charts using the MCP Apps extension.
What you can do with it
- 1Analyze futures market sentimentCompare funding rates and open interest across multiple venues for a specific coin.
Written from the project's README. Every use case is checked against a quote from it.
How to install BlackForge MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall BlackForge MCP in Claude Code
$ claude mcp add --env 'BLACKFORGE_API_KEY=<YOUR_BLACKFORGE_API_KEY>' mcp -- npx -y @blackforge-so/mcpInstall BlackForge MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@blackforge-so/mcp"
],
"env": {
"BLACKFORGE_API_KEY": "<YOUR_BLACKFORGE_API_KEY>"
}
}
}
}Install BlackForge MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@blackforge-so/mcp"
],
"env": {
"BLACKFORGE_API_KEY": "<YOUR_BLACKFORGE_API_KEY>"
}
}
}
}Install BlackForge MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@blackforge-so/mcp"],"env":{"BLACKFORGE_API_KEY":"<YOUR_BLACKFORGE_API_KEY>"}}'Install BlackForge MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@blackforge-so/mcp"
],
"env": {
"BLACKFORGE_API_KEY": "<YOUR_BLACKFORGE_API_KEY>"
}
}
}
}Install BlackForge MCP in Codex
$ codex mcp add mcp --env 'BLACKFORGE_API_KEY=<YOUR_BLACKFORGE_API_KEY>' -- npx -y @blackforge-so/mcpInstall BlackForge MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] command = "npx" args = ["-y", "@blackforge-so/mcp"] [mcp_servers.mcp.env] BLACKFORGE_API_KEY = "<YOUR_BLACKFORGE_API_KEY>"
Install BlackForge MCP in Gemini CLI
$ gemini mcp add -s user -e 'BLACKFORGE_API_KEY=<YOUR_BLACKFORGE_API_KEY>' mcp npx -- -y @blackforge-so/mcpInstall BlackForge MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@blackforge-so/mcp"
],
"env": {
"BLACKFORGE_API_KEY": "<YOUR_BLACKFORGE_API_KEY>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @blackforge-so/mcp 0.5.0 in an isolated container with no network and no keys. It answered and listed 21 tools.
BlackForge MCP tools 21
Read from the server with tools/listblackforge_catalogRead-onlyList every venue BlackForge covers (the major spot exchanges) and every column it measures (one wide row per (exchange, symbol) per minute, served at 1m, 5m, 1h and 1d: order-book depth and shape, resting-liquidity lifetimes, trade-explained vs book-implied volume, spreads, and market-wide context). `metricCount` is the exact number of columns available now. Each metric carries a precise measurement definition, unit, family, and the minimum plan that includes it, the `intervals` it is served at, and, where the 5m/1h/1d value is a rollup of minute values rather than a re-measurement, a one-sentence `rollupNote`. `availableFrom["1m"]` is when the one-minute rows start (null before). `availableFrom.bookOnBoundary` maps each venue to the first window end whose order book was read as it stood at that instant (such rows have `bookObservedAt` equal to `ts`, so venues line up), null before; the order book columns carry a one-sentence `bookTimingNote` on it. The `qualityFlags` metric also carries the `bits` table that decodes the per-row quality mask. `futures` describes the linear futures contracts (perpetual and dated) on the major futures venues, read by the blackforge_futures_* tools: its own `venues` (each with `minPlan` and `liquidations`: complete, lowerBound or null), `metrics` (prices, funding, open interest, taker flow, liquidations), the `qualityBits` table that decodes a futures row's quality mask, `liquidationEvents` (the plan the event feed needs and its fields), `availableFrom` and `historyDays` (futures history is a rolling window); `futuresMetricCount` is the number of futures columns sold. This route needs no API key. CALL THIS FIRST to learn the exact `exchange` and `metric` identifiers the other tools accept.
blackforge_symbolsRead-onlyList the trading pairs (symbols) a given venue trades, as an array of symbol strings. Use these values as the `symbol` argument to blackforge_latest and blackforge_series. Valid `exchange` values come from blackforge_catalog (e.g. binance, bybit, coinbase, kraken, okx). A venue outside the caller's plan returns HTTP 403 with the plan and an upgrade URL.
blackforge_latestRead-onlyReturn the latest completed bucket for one (exchange, symbol), at the key plan's interval (1 minute on Ultra and PAYG, 5 minutes otherwise): a `values` object mapping each column key to its measured number (or null when not observed), plus the window END timestamp `ts` in epoch milliseconds. Omit `columns` to get every column your plan includes; pass a subset of column keys (from blackforge_catalog) to narrow the payload. Columns your plan does not cover are dropped and reported in `columnsOmitted` so you can see why a key is absent. WHEN PRESENT, a `quality` object reports the row's measurement quality: `flags` names what went wrong during the window and `contaminates` lists which figures it flags, with a plain-English `qualityNote` beside it. Read it before trusting an unusual value. A `quality.raw` of 32768 means the row predates the quality rail and was never assessed; that is unknown, not bad. When the key is absent, the row carries no quality assessment at all.
blackforge_seriesRead-onlyReturn a time series for one column of one (exchange, symbol): `points` is an ascending array of { ts, value } where `ts` is epoch milliseconds and `value` is the measured number (or null). `from`/`to` are ISO-8601 datetimes; `interval` is one of 1m, 5m, 1h, 1d. 1m is on Ultra and PAYG (PAYG bills a 1m row at five times a 5m row); Max and below go down to 5m, and a finer interval than the plan allows is a 403. 1m rows exist only from the switch to one-minute rows on (see blackforge_catalog `availableFrom`); for earlier ranges use 5m, which covers all history. The server caps a response at 50,000 points (about 34 days at 1m) and keeps the NEWEST; `truncated: true` says the range was cut, so narrow it or use a coarser interval. If the requested `metric` is above your plan, `points` comes back empty and the column is listed in `columnsOmitted`, which is why it is empty. WHEN ANY BUCKET IS FLAGGED, a `qualitySummary` object reports how many of the buckets carry a quality flag and which flags they are (`{ flaggedBuckets, of, flags }`); per-bucket quality is deliberately not repeated on every point. No `qualitySummary` means no bucket in the range was flagged.
blackforge_usageRead-onlyReport the calling key's recent usage: `days` is a per-day breakdown of request counts and the last request time, and `rowsRemaining` is the monthly row quota still available (omitted for usage-based plans that have no monthly ceiling). Use this to check headroom before a large pull.
blackforge_futures_symbolsRead-onlyThe linear futures contracts (perpetual and dated) a futures venue lists now, as an array of contract symbols: the `symbol` values blackforge_futures_latest and blackforge_futures_series accept. Contracts are spelled the way each venue spells them: binance, bybit and bitget `BTCUSDT`, okx `BTC-USDT-SWAP`, gate and mexc `BTC_USDT`, kucoin `XBTUSDTM`, dated contracts such as `BTCUSDT_261225`. The futures venues and the plan each needs are under `futures.venues` in blackforge_catalog; a venue outside the key's plan is an HTTP 403 carrying the plan and an upgrade URL. Not metered.
blackforge_futures_latestRead-onlyThe latest complete bucket for one linear futures contract at the key plan's interval (1m on Ultra and PAYG, 5m on Max, 1h on Pro, 1d on Free). `values` maps each futures column key to its value: a number, a string for the text columns (`baseAsset`, `quoteAsset`, `contractType`), or null where the venue did not publish it. `ts` (epoch milliseconds, with `tsIso`) and `interval` identify the bucket; `ts` is 0 with empty `values` when the contract has no row. The columns are defined under `futures.metrics` in blackforge_catalog: mark, index, last, best bid and best ask prices; `fundingRate` (per funding interval, a fraction: 0.0001 = 0.01%; venues settle at different intervals) and `nextFundingTime`; `openInterest` (base units) and `openInterestValue` (quote currency) with `openInterestAt`; volume, taker buy volume and trade count; and long and short liquidation counts and notionals (Max and up). `columns` narrows the payload; columns above the plan are dropped and listed in `columnsOmitted`. When present, `quality` holds the row's futures quality `flags` and the column families they call into question (`contaminates`), with a plain-English `qualityNote`; the decode table is `futures.qualityBits` in blackforge_catalog. Contracts are spelled the way each venue spells them: binance, bybit and bitget `BTCUSDT`, okx `BTC-USDT-SWAP`, gate and mexc `BTC_USDT`, kucoin `XBTUSDTM`, dated contracts such as `BTCUSDT_261225`.
blackforge_futures_seriesRead-onlyA time series of one numeric futures column for one contract: `points` is an ascending array of { ts, value } with `ts` in epoch milliseconds and `value` the number or null. `from`/`to` are ISO-8601 datetimes; `interval` is one of 1m, 5m, 1h, 1d, and an interval finer than the plan's (1m on Ultra and PAYG, 5m on Max, 1h on Pro, 1d on Free) is an HTTP 403. Futures history is a rolling window: `futures.historyDays` and `futures.availableFrom` in blackforge_catalog, shorter on Free; a `from` before the plan's window is moved forward to it without an error, so the first point can start later than asked. Flows (volume, taker volume, trades, liquidations) are summed into a bucket; prices, funding and open interest are the bucket's last minute (`rollup` on each catalog entry). At most 50,000 points, newest kept, with `truncated: true` when cut. A column above the plan comes back with empty `points` and is listed in `columnsOmitted`. When any bucket is flagged, `qualitySummary` (`{ flaggedBuckets, of, flags }`) names the futures quality flags; no `qualitySummary` means no bucket in the range was flagged.
blackforge_futures_topRead-onlyFutures contracts ranked by one numeric column on the latest complete bucket at the key plan's interval, on one venue (`exchange`) or across every futures venue the plan includes. `rows` is an array of { exchange, symbol, baseAsset, value } in `order` (`desc`, the default, is largest first), with the bucket's `ts` (epoch milliseconds, with `tsIso`) and `interval`. `baseAsset` (e.g. BTC) keeps one coin, which with no `exchange` puts that coin's contracts on every venue side by side; `contractType` keeps `perpetual` or `dated` contracts. `limit` is 1 to 100 (default 50). `metric` is a numeric key from blackforge_catalog `futures.metrics`, e.g. fundingRate, openInterestValue, quoteVolume, or liqLongNotional (Max and up). A funding rate is per the venue's funding interval, which is not the same on every venue.
blackforge_futures_liquidationsRead-onlyIndividual liquidation events from the futures venues that publish a public liquidation feed, newest first. `events` is an array of { ts, exchange, symbol, side, price, quantity, notional }: `ts` is the venue's time in epoch milliseconds, `side` is the POSITION liquidated (a long is closed by a forced sell), `quantity` is in base units and `notional` in the quote currency. `from`/`to` (ISO-8601) default to the last hour, echoed as `fromIso`/`toIso`; `limit` is 1 to 1000 (default 100) and `truncated: true` means the window held more. Feed coverage per venue is `futures.venues[].liquidations` in blackforge_catalog: `complete` sends every liquidation, `lowerBound` is throttled by the venue so a cascade is undercounted, null publishes none; `feedNote` names the lower-bound venues present in the result. Max, Ultra and PAYG; below Max this is an HTTP 403 with an upgrade URL.
blackforge_formula_validateRead-onlyCheck a live formula without saving it. Free and unmetered, so iterate on it freely. On success returns { ok: true, normalised, pairs, primitives, horizonSeconds, cost: { rowsPerEvaluation, rowsPer30Days } }. On a refusal returns { ok: false, error } where error carries a stable code, a message, the location (at, pointer under the source) and suggestions such as the correct pair spelling: apply them and check again. A formula is an arithmetic expression over live order book and trade data, evaluated server-side every interval (default 1 s). Pairs are written venue:SYMBOL exactly as blackforge_symbols spells them (binance:BTCUSDT, okx:BTC-USDT, coinbase:BTC-USD), and one formula may combine pairs on different venues. Durations are 1s to 60s, or 1m. Book state, read now: bid ask bidQty askQty mid spread spreadBps bidLevels askLevels quoteUsd last lastAge, each (pair). Book walk: bidDepth askDepth imbalance (pair, bps) with bps an integer 1 to 200 written as a number; buyCost sellCost (pair, usd) with usd 100 to 1000000, result in bps. Trades over a window: buyVol sellVol vol buyUsd sellUsd volUsd buyCount sellCount tradeCount netFlow buyShare vwap high low open close maxBuy maxSell (pair, duration); buyUsdAbove sellUsdAbove buyCountAbove sellCountAbove (pair, duration, usd) with usd one of 100, 1000, 10000, 100000. Book changes over a window: bidAdded askAdded bidRemoved askRemoved bidAddedNear askAddedNear bidRemovedNear askRemovedNear bookChanges (pair, duration). Scalar: abs sign sqrt ln log10 exp pow min max clamp round floor ceil if coalesce. Windows over any expression: avgOver minOver maxOver stdOver change pctChange (expr, duration). Operators + - * / ^, comparisons, and, or, not. A missing input gives null, never a made-up number. The sum of windows on any path (the horizon) is at most 60 s. Examples: mid(binance:BTCUSDT) - mid(okx:BTC-USDT); imbalance(binance:ETHUSDT, 50); buyVol(binance:SOLUSDT, 60s) / max(sellVol(binance:SOLUSDT, 60s), 1); avgOver(spreadBps(kraken:XBTUSD), 1m). Live formulas and notifications are part of the Ultra plan.
blackforge_formula_createActionSave a live formula to the account so it can be streamed (blackforge_formula_watch) and carry notifications (blackforge_alert_create). Returns { formula: { id, name, expr, interval, pairs, horizonSeconds, ... } }. A refused formula comes back as an error with the same located, coded detail blackforge_formula_validate gives; validate first. Saving is free; a formula is charged one row per referenced pair per evaluation only while it is streamed or watched by a notification. Live formulas and notifications are part of the Ultra plan.
Show all 21 toolsShow fewer tools
blackforge_formula_listRead-onlyList the account's saved live formulas, with the plan's limits and current usage ({ formulas, limits, usage: { live, stored, connections } }). Live formulas and notifications are part of the Ultra plan.
blackforge_formula_deleteActionDelete a saved live formula. Its notifications are deleted with it and listed in deletedAlerts. Cannot be undone.
blackforge_formula_watchRead-onlyStream a live formula for a few seconds and return what arrived: first, last, min, max, the number of samples, which value flags appeared (with a plain note for each), and the full series of { ts, value, flags? } with ts in epoch milliseconds. Pass formulaId for a saved formula, or expr to watch a formula once (it is saved as a one-hour formula first). seconds is 1 to 60, default 20. A value flagged WARMING is computed over less than its full window, because the formula is younger than its horizon; it settles by warmUntil. null means there was no number (for example no print in a trade window), never zero. Charged one row per referenced pair per evaluation. Live formulas and notifications are part of the Ultra plan.
blackforge_alert_createActionGet notified when a saved live formula crosses a value you set. It is evaluated server-side every interval, whether or not anything is connected. direction: above (goes from at or below the threshold to above it), below (the reverse), or cross (either). After it fires it waits until the value is back on the other side by at least hysteresis and cooldownSeconds (60 to 86400, default 900) have passed. If the condition is already true when created, it starts disarmed and arms once the value is back across. It never fires on null or on a WARMING or stale value. Email goes to the account's verified address (default on); webhookUrl (https) optionally receives a signed POST. The response carries webhookSecret ONCE: store it to verify the x-blackforge-signature header (t=<unix>,v1=<hex HMAC-SHA256 of t.body>). Live formulas and notifications are part of the Ultra plan.
blackforge_alert_listRead-onlyList the account's formula notifications ({ alerts, limits }). Each carries its formula, direction, threshold, status (active, paused, quota, plan), whether it is armed, and when it last fired. Live formulas and notifications are part of the Ultra plan.
blackforge_alert_deleteActionDelete a formula notification. The formula itself is kept. Cannot be undone.
blackforge_bookRead-onlyRead the live order book for one pair right now: the top levels on both sides as [price, quantity] pairs, when it was read (observedAtMs), whether the book is synced or crossed, and level counts. levels is 1 to 200, default 20. Charged 2 rows per level returned. Live order book reads need the Max or Ultra plan and are charged against the monthly row quota.
blackforge_fillRead-onlyWalk the live order book to price a market order of a given size right now, without placing anything. Give usd (notional in USD) or size (base quantity). Returns { complete, bps, partialBps, levelsWalked, vwap, depthLimited, bookExhausted }: bps is the cost against the mid in basis points and is null unless the visible book could fill the whole order (then see partialBps, and do not quote it as the cost). Charged one row per level walked. Live order book reads need the Max or Ultra plan and are charged against the monthly row quota.
blackforge_spread_mapRead-onlyBest bid and best ask for one base/quote pair on every venue that lists it, all read within the same moment, so a difference between venues is a real difference rather than a timing artefact. Charged 2 rows per venue. Live order book reads need the Max or Ultra plan and are charged against the monthly row quota.
Configuration
BLACKFORGE_API_KEYSecretBlackForge API key. Every tool except blackforge_catalog requires one.
BLACKFORGE_BASE_URLAPI base URL. Defaults to https://api.blackforge.so.
BLACKFORGE_REALTIME_URLRealtime host for live formulas and live order book reads. Defaults to https://realtime.blackforge.so.
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableblackforge-so/mcp is public and reachablegithub.com/blackforge-so/mcp ↗Pass
- Package names this repository as its source@blackforge-so/mcp names blackforge-so/mcp as sourcenpmjs.com/package/@blackforge-so/mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/blackforge-so/mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @blackforge-so/mcpPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model21 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@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.
Tools
| Tool | Returns |
|---|---|
blackforge_catalog |
Every venue and every column definition, with metricCount the live column count. Keyless. Call this first to learn valid exchange and metric identifiers. |
blackforge_symbols |
The trading pairs a venue lists, e.g. ["BTCUSDT", …]. |
blackforge_latest |
The latest completed bucket for one (exchange, symbol) at the plan's interval (1 minute on Ultra and PAYG, 5 minutes otherwise): a values object of column → number, with epoch-ms ts. Pass columns to narrow it. |
blackforge_series |
A time series for one column over a range: ascending { ts, value } points at 1m (Ultra and PAYG), 5m, 1h, or 1d. Capped at 50,000 points, newest kept, truncated: true when cut. One-minute rows start at the switch to one-minute rows (availableFrom in the catalog); 5m covers all history. |
blackforge_usage |
The key's recent request counts and remaining monthly row quota. |
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.
| Tool | Returns | Plan |
|---|---|---|
blackforge_futures_symbols |
The contracts a futures venue lists, spelled the way the venue spells them (BTCUSDT, BTC-USDT-SWAP, BTC_USDT, XBTUSDTM). |
Every plan |
blackforge_futures_latest |
The latest complete bucket for one contract at the plan's interval: a values object (numbers, plus baseAsset, quoteAsset and contractType as text), ts, interval, and the row's quality when present. |
Every plan |
blackforge_futures_series |
One futures column over a range at 1m, 5m, 1h or 1d, with the same chart widget as blackforge_series and a qualitySummary when a bucket is flagged. |
Every plan |
blackforge_futures_top |
Contracts ranked by one column on the latest bucket, on one venue or across all of them; baseAsset: "BTC" puts one coin's funding or open interest on every venue side by side. |
Every plan |
blackforge_futures_liquidations |
Liquidation events, newest first (side is the position liquidated), the last hour by default, with a feedNote when a venue in the result throttles its feed. |
Max, Ultra, PAYG |
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.
| Tool | Does | Plan |
|---|---|---|
blackforge_formula_validate |
Checks a formula without saving it. Free. A refusal comes back as data: a stable code, the location with a pointer under the source, and suggestions (e.g. the venue's real pair spelling), so an agent can fix it and check again. |
Ultra |
blackforge_formula_create |
Saves a formula (name, expr, interval 1 to 60 s). |
Ultra |
blackforge_formula_list |
Saved formulas, your limits and current usage. | Ultra |
blackforge_formula_delete |
Deletes a formula and the notifications on it. | Ultra |
blackforge_formula_watch |
Streams a saved formula (formulaId) or a one-off expr for up to 60 s (default 20) and returns first, last, min, max, the flags seen and the full series. |
Ultra |
blackforge_alert_create |
Notifies you when a formula crosses a value you set (above, below, cross), by email and optionally a signed webhookUrl. The webhook secret is shown once. |
Ultra |
blackforge_alert_list / blackforge_alert_delete |
List or delete notifications. | Ultra |
blackforge_book |
The live order book for one pair, up to 200 levels a side. | Max, Ultra |
blackforge_fill |
Prices a market order against the live book (usd or size); bps is null unless the visible book fills it all. |
Max, Ultra |
blackforge_spread_map |
Best bid and ask for one base/quote on every venue that lists it, read in the same moment. | Max, Ultra |
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
| Env var | Default | Purpose |
|---|---|---|
BLACKFORGE_API_KEY |
(none) | Your key. Required for every tool except blackforge_catalog. |
BLACKFORGE_BASE_URL |
https://api.blackforge.so |
API base. Paths are appended as /v1/.... Override for a self-hosted or local dev API (e.g. http://localhost:3001/api). |
BLACKFORGE_REALTIME_URL |
https://realtime.blackforge.so |
Realtime host for the live formula stream and the live order book reads. |
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
BlackForge MCP questions
How do I add BlackForge MCP to Claude Code?
Run claude mcp add --env 'BLACKFORGE_API_KEY=<YOUR_BLACKFORGE_API_KEY>' mcp -- npx -y @blackforge-so/mcp in your terminal. Add --scope user to make it available in every project.
How do I add BlackForge MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does BlackForge MCP provide?
It exposes 21 tools, including blackforge_catalog, blackforge_symbols, blackforge_latest, blackforge_series, blackforge_usage.
Can I test the server without an API key?
Yes, the blackforge_catalog tool works without a key, allowing you to verify your installation before providing one.
What kind of crypto exchanges are supported?
The server provides data from major exchanges including Binance, Bitget, Bybit, Coinbase, Gate, Kraken, Kucoin, MEXC, and OKX.
Does the server support futures data?
Yes, it reads linear futures contracts including funding rates, open interest, prices, taker flow, and liquidations.