@blackforge-so/mcp

A Model Context Protocol stdio server that puts BlackForge market-data in your agent's hands. The whole crypto market, in real time — nine spot venues (binance, bitget, bybit, coinbase, gate, kraken, kucoin, mexc, okx), ~13,800 pairs, up to 117 measurement columns per pair per closed 5-minute window.

Every column is a measurement with a definition — order-book depth and shape, resting liquidity lifetimes, trade-explained vs book-implied volume, spreads, 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 → Keys. 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 (9 venues, 103 metrics). 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 5-minute window for one (exchange, symbol) — 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 5m, 1h, or 1d. Capped at 50,000 points. | | 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).

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

Local development

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

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