Blackforge So MCP

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:

{
  "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.