# BlackForge MCP server

> Provides real-time crypto market data, including spot order books, futures funding, open interest, and liquidations from major exchanges.

- Repository: https://github.com/blackforge-so/mcp
- Page: https://hostedmcp.org/servers/blackforge-so/mcp
- Transport: stdio
- Stars: 0
- License: MIT
- Latest version: 0.5.0

## Install

### Claude Code

```sh
claude mcp add --env 'BLACKFORGE_API_KEY=<YOUR_BLACKFORGE_API_KEY>' mcp -- npx -y @blackforge-so/mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@blackforge-so/mcp"
      ],
      "env": {
        "BLACKFORGE_API_KEY": "<YOUR_BLACKFORGE_API_KEY>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@blackforge-so/mcp"
      ],
      "env": {
        "BLACKFORGE_API_KEY": "<YOUR_BLACKFORGE_API_KEY>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@blackforge-so/mcp"],"env":{"BLACKFORGE_API_KEY":"<YOUR_BLACKFORGE_API_KEY>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@blackforge-so/mcp"
      ],
      "env": {
        "BLACKFORGE_API_KEY": "<YOUR_BLACKFORGE_API_KEY>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add mcp --env 'BLACKFORGE_API_KEY=<YOUR_BLACKFORGE_API_KEY>' -- npx -y @blackforge-so/mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.mcp]
command = "npx"
args = ["-y", "@blackforge-so/mcp"]

[mcp_servers.mcp.env]
BLACKFORGE_API_KEY = "<YOUR_BLACKFORGE_API_KEY>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'BLACKFORGE_API_KEY=<YOUR_BLACKFORGE_API_KEY>' mcp npx -- -y @blackforge-so/mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@blackforge-so/mcp"
      ],
      "env": {
        "BLACKFORGE_API_KEY": "<YOUR_BLACKFORGE_API_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `BLACKFORGE_API_KEY` | no | yes | BlackForge API key. Every tool except blackforge_catalog requires one. |
| `BLACKFORGE_BASE_URL` | no | no | API base URL. Defaults to https://api.blackforge.so. |
| `BLACKFORGE_REALTIME_URL` | no | no | Realtime host for live formulas and live order book reads. Defaults to https://realtime.blackforge.so. |

## Tools (21)

- `blackforge_catalog`: List 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. (read-only)
- `blackforge_symbols`: List 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. (read-only)
- `blackforge_latest`: Return 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. (read-only)
- `blackforge_series`: Return 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. (read-only)
- `blackforge_usage`: Report 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. (read-only)
- `blackforge_futures_symbols`: The 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. (read-only)
- `blackforge_futures_latest`: The 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`. (read-only)
- `blackforge_futures_series`: A 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. (read-only)
- `blackforge_futures_top`: Futures 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. (read-only)
- `blackforge_futures_liquidations`: Individual 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. (read-only)
- `blackforge_formula_validate`: Check 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. (read-only)
- `blackforge_formula_create`: Save 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.
- `blackforge_formula_list`: List 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. (read-only)
- `blackforge_formula_delete`: Delete a saved live formula. Its notifications are deleted with it and listed in deletedAlerts. Cannot be undone.
- `blackforge_formula_watch`: Stream 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. (read-only)
- `blackforge_alert_create`: Get 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_list`: List 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. (read-only)
- `blackforge_alert_delete`: Delete a formula notification. The formula itself is kept. Cannot be undone.
- `blackforge_book`: Read 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. (read-only)
- `blackforge_fill`: Walk 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. (read-only)
- `blackforge_spread_map`: Best 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. (read-only)

## FAQ

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