blackforge

Name: blackforge
Author: blackforge.so

本地服务

blackforge.so金融数据01 天前更新

代码仓库访问官网

关于 blackforge

blackforge 是面向 Agent 的加密货币市场数据 MCP 服务，覆盖九家现货交易平台及订单簿、流动性和交易量等指标。它也支持实时公式、行情监控与告警，并直接调用 BlackForge API。

主要功能

01查询九家平台的市场指标
02获取交易对与历史序列
03查看实时订单簿和价差
04创建并监控实时公式
05设置指标越界告警

适用场景

01比较不同平台的现货市场数据
02分析交易对的历史指标变化
03监控订单簿并估算市价单成交
04在公式触发条件时接收通知

MCP 相关

这是一个通过 stdio 提供的 MCP 服务，将 BlackForge 市场数据 API 的查询、实时公式、订单簿和告警功能开放给 MCP 客户端。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

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

启动命令npx -y @blackforge-so/mcp

需要配置的环境变量

BLACKFORGE_API_KEY密钥BlackForge 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.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@blackforge-so/mcp0.4.2stdio

工具

收录的工具列表 · 更新于今天

此工具无需参数。

详细介绍

@blackforge-so/mcp

一个 Model Context Protocol stdio 服务，让你的 Agent 能使用 BlackForge 市场数据。实时掌握整个加密货币市场 — 覆盖九家现货交易所（binance、bitget、bybit、coinbase、gate、kraken、kucoin、mexc、okx），并提供每个交易对在每个已收盘分钟的所有测量列（Ultra 和 PAYG 提供 1m 数据；所有套餐均提供 5m、1h 和 1d 汇总数据）。

每一列都是有明确定义的测量值——盘口深度与形态、挂单流动性持续时间、成交量（按成交解释与按盘口推算）、价差、全市场背景信息——这些数据会直接返回到上下文中，让 Agent 能直接读取原始微观结构数据。它是公共 BlackForge /v1 API 的轻量客户端；不存储数据，也不重新整理数据。

快速开始

将服务添加到你的 MCP 客户端并粘贴 API 密钥。适用于 Claude Desktop （claude_desktop_config.json）或 Claude Code（.mcp.json）：

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

无需安装步骤——npx -y @blackforge-so/mcp 会按需获取并运行该服务。

如何获取密钥

在 app.blackforge.so → API 创建密钥。服务不会创建密钥；它会从环境中读取 BLACKFORGE_API_KEY。blackforge_catalog 工具无需密钥即可使用，因此你可以先验证安装是否成功，再粘贴密钥。

工具

工具	返回内容
`blackforge_catalog`	所有交易所和所有列的定义——共 9 家交易所，`metricCount` 表示当前列数。无需密钥。请先调用此工具，以了解有效的 `exchange` 和 `metric` 标识符。
`blackforge_symbols`	某家交易所列出的交易对，例如 `["BTCUSDT", …]`。
`blackforge_latest`	某个 `(exchange, symbol)` 在套餐对应时间间隔下的最新完整数据桶（Ultra 和 PAYG 为 1 分钟，其余套餐为 5 分钟）——包含列 → 数值映射的 `values` 对象，以及以毫秒为单位的纪元时间 `ts`。传入 `columns` 可缩小范围。
`blackforge_series`	某个列在指定范围内的时间序列：按时间升序排列的 `{ ts, value }` 数据点，间隔为 `1m`（Ultra 和 PAYG）、`5m`、`1h` 或 `1d`。最多返回 50,000 个数据点，保留最新数据；截断时返回 `truncated: true`。1 分钟数据行从切换到 1 分钟数据行时开始（目录中的 `availableFrom`）；`5m` 覆盖全部历史数据。
`blackforge_usage`	密钥最近的请求次数，以及每月剩余的数据行配额。

API 会强制执行套餐权限（密钥可读取的交易所、列和时间间隔）。如果某列因套餐不包含该列而被省略，工具结果会通过 columnsOmitted 报告，让 Agent 了解缺少该列的原因。交易所或时间间隔级别的限制会以明确的工具错误返回，其中包含 HTTP 状态码和服务端消息（包括原样返回的升级 URL）。

实时公式与实时订单簿

除了已存储的历史数据外，服务还会连接 BlackForge 的实时主机。你可以根据各大交易平台的订单簿和成交数据编写自己的指标，每秒推送一次，并在指标越过你设定的值时收到通知。

工具	功能	方案
`blackforge_formula_validate`	检查公式，但不保存。免费。如果拒绝执行，会以数据形式返回结果：稳定的 `code`、源内容中对应位置的 `pointer`，以及 `suggestions`（例如交易平台上的实际交易对拼写），方便 Agent 修正后再次检查。	Ultra
`blackforge_formula_create`	保存公式（`name`、`expr`、`interval`，间隔为 1 到 60 s）。	Ultra
`blackforge_formula_list`	查看已保存的公式、使用限额和当前用量。	Ultra
`blackforge_formula_delete`	删除公式及其相关通知。	Ultra
`blackforge_formula_watch`	最长 60 s（默认 20 s）内推送已保存的公式（`formulaId`）或一次性 `expr`，并返回首值、末值、最小值、最大值、出现过的标志以及完整序列。	Ultra
`blackforge_alert_create`	当公式越过你设定的值（`above`、`below`、`cross`）时，通过电子邮件通知你，也可选择使用签名的 `webhookUrl`。Webhook 密钥只会显示一次。	Ultra
`blackforge_alert_list` / `blackforge_alert_delete`	列出或删除通知。	Ultra
`blackforge_book`	查看单个交易对的实时订单簿，每侧最多 200 档。	Max、Ultra
`blackforge_fill`	根据实时订单簿计算市价单的成交价格（`usd` 或 `size`）；只有可见订单簿完全满足成交量时，`bps` 才会有值，否则为 null。	Max、Ultra
`blackforge_spread_map`	在同一时刻读取所有上架该基础货币／计价货币组合的交易平台上的最佳买价和卖价。	Max、Ultra

公式示例：mid(binance:BTCUSDT) - mid(okx:BTC-USDT) 或 buyVol(binance:SOLUSDT, 60s) / max(sellVol(binance:SOLUSDT, 60s), 1)。交易对的拼写必须与 blackforge_symbols 列出的完全一致。完整的函数列表请参阅 blackforge_formula_validate 工具说明。推送和通知按每次计算中引用的每个交易对各计一行；实时订单簿读取按返回或遍历的档位数计费，与其他所有用量共用同一月度配额。每个推送值都带有 flags（例如，当窗口函数的窗口尚未填满时会标记为 WARMING）；null 表示没有数值，绝不表示零。

推送使用 Node 内置的 WebSocket，因此 blackforge_formula_watch 需要 Node 22 或更新版本；其他所有工具均在 Node 20 上运行。你的密钥会通过 x-api-key 请求头传递，绝不会放在 URL 中。

图表

blackforge_series 还提供交互式图表。实现了 MCP Apps 扩展（io.modelcontextprotocol/ui）的宿主会将结果呈现为折线图，并按照 BlackForge 控制台使用的相同方式绘制带标志的分桶数据；其他宿主看到的 JSON 与以往完全相同。

工具契约没有任何变化。图表载荷通过结果的 _meta 传递；它属于协议元数据，不会传给任何模型。因此，无论宿主是否渲染小组件，content[0].text 都逐字节完全相同，序列的 token 成本也完全一致。这是有意为之：structuredContent 看似是存放图表载荷的理想位置，但核心 MCP 将该字段视为由服务生成的结果数据；不支持 Apps 的宿主可能会把它传给模型，从而使大型序列的成本翻倍。

图表是一个自包含的 HTML 文件，uPlot 和所有 CSS 都内嵌其中，因为 MCP Apps 会在默认拒绝的 CSP 下渲染，外部 <script> 根本无法加载。图表为只读，不会回调服务：它只绘制收到的点，不会在你不知情的情况下消耗行配额。超过 2,000 个点的序列只会为图表进行抽稀——工具仍会返回所有点——且载荷会明确说明这一点，而不会悄悄减少折线上的点数。

数据质量

当 API 报告某行的测量质量时，blackforge_latest 会通过 quality 对象（flags 命名窗口中出现的问题，contaminates 列出受其标记影响的数据）以及纯英文的 qualityNote 将其传递出来。blackforge_series 会将其汇总为一个 qualitySummary（{ flaggedBuckets, of, flags }），而不是在每个数据点上重复显示。若没有任何标记，这两个键都会完全省略；quality.raw 为 32768 表示该行早于质量监测机制，且从未经过评估——这是未知，而非质量差。标记解码表位于 blackforge_catalog 中的 qualityFlags 指标上，格式为 bits 数组；此服务会从那里读取，不会保存自己的副本。

配置

环境变量	默认值	用途
`BLACKFORGE_API_KEY`	(无)	你的密钥。除 `blackforge_catalog` 外，每个工具都需要此密钥。
`BLACKFORGE_BASE_URL`	`https://api.blackforge.so`	API 基础 URL。路径会以 `/v1/...` 的形式追加。可覆盖此值，以使用可自托管或本地开发 API（例如 `http://localhost:3001/api`）。
`BLACKFORGE_REALTIME_URL`	`https://realtime.blackforge.so`	实时公式流和实时订单簿读取所用的实时主机。

本地开发

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

build 会先运行 tsup，再构建 widget 的 vite；这个顺序至关重要：tsup 的 clean 会清空整个 dist/，因此若颠倒顺序，就会删除 widget，导致服务端提供一个不存在的资源。

集成测试会通过 stdio 启动构建后的服务端，并使用 MCP 客户端驱动它。数据断言需要本地 BlackForge API，地址为 http://localhost:3001/api；如果没有，则会跳过这些断言，但仍会运行工具列表检查。