# blackforge-so/mcp [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/blackforge-so/mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1172  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-390

## Description
Crypto market data: order book depth, liquidity lifetimes and taker flow on 9 spot venues

## Tools
Capabilities this server exposes over MCP:

- **blackforge_catalog** — List every venue BlackForge covers (9 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. This route needs no API key. CALL THIS FIRST to learn the exact `exchange` and `metric` identifiers the other tools accept.
- **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.
- **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.
- **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.
- **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.
- **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.
- **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.
- **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.
- **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.
- **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.
- **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.
- **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.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

**Requires environment variables:** `BLACKFORGE_API_KEY`, `BLACKFORGE_BASE_URL`, `BLACKFORGE_REALTIME_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What blackforge-so/mcp does

blackforge-so/mcp exposes BlackForge crypto market data through the Model Context Protocol. The service covers Binance, Bitget, Bybit, Coinbase, Gate, Kraken, KuCoin, MEXC, and OKX, with more than 150 metrics across thousands of trading pairs. Available measurements include order-book depth and shape, liquidity lifetimes, spreads, trade-versus-book volume, and broader market context.

The server is a thin client for BlackForge's public `/v1` API. It does not maintain a local data store or reshape the returned measurements. API plan entitlements determine which venues, columns, and intervals a key can access.

## How it works

Start with `blackforge_catalog` to discover valid venue and metric identifiers. It is the only keyless tool and also describes the available columns, live metric count, data availability, and quality flag meanings. Use `blackforge_symbols` to obtain the exact pair spelling for a venue before requesting data.

`blackforge_latest` returns the newest completed bucket for one venue and symbol. `blackforge_series` returns ascending points for a selected metric and range at 1-minute, 5-minute, hourly, or daily resolution, subject to the plan and a 50,000-point response cap. The newest points are retained when the cap is reached. `blackforge_usage` reports recent request counts and remaining monthly row quota.

Realtime operations use a separate host. Formula tools can validate, save, list, delete, and watch expressions based on live order-book and trade data. Formula watches run for a limited period and report statistics, flags, and the observed series. Ultra plans can create alerts for values moving above, below, or across a threshold, with email and optional signed webhook notifications. Max and Ultra plans provide live book reads, market-order fill estimates, and cross-venue spread maps.

## Setup and configuration

The package can run on demand through `npx`:

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

Claude Desktop uses this configuration in `claude_desktop_config.json`; Claude Code uses `.mcp.json`. Create an API key through the BlackForge API page. `BLACKFORGE_API_KEY` is required for all tools except the catalog.

`BLACKFORGE_BASE_URL` changes the HTTP API base URL and defaults to `https://api.blackforge.so`. `BLACKFORGE_REALTIME_URL` changes the realtime host and defaults to `https://realtime.blackforge.so`. The realtime formula watch requires Node.js 22 or newer; the other tools run on Node.js 20.

## Tools and capabilities

- Discover venues, metric definitions, pair symbols, and data availability.
- Read the latest completed metric bucket or retrieve historical series.
- Inspect API usage and remaining monthly row quota.
- Validate, save, monitor, list, and delete live formulas.
- Create, list, and remove threshold alerts.
- Read live order books, estimate market-order execution, and compare venue spreads.
- Render `blackforge_series` as an interactive chart in MCP Apps hosts; other clients receive the JSON result.

Quality information is preserved when available. Latest values can include flags and a quality note, while series responses summarize flagged buckets. A null live formula value means no number was available, rather than zero.

## Limitations and notes

Plan restrictions are enforced by the BlackForge API. Omitted columns are identified in `columnsOmitted`, while venue or interval restrictions produce tool errors containing the API status and message. One-minute history begins at the availability boundary recorded in the catalog; five-minute data covers the available historical range.

Live formula streaming and notifications consume quota based on referenced pairs and evaluation frequency. Live book usage is charged according to levels returned or traversed. Chart rendering may decimate series longer than 2,000 points for display only; the tool response still contains the full series. The chart is read-only and does not make additional server requests.

The package is licensed under MIT.

_Full upstream README: https://allmcps.com/mcp/mcp-390/readme_