xbbg MCP

xbbg-mcp

最后更新：2026-10-20。

基于 xbbg-async 的 Bloomberg 请求/响应工作流 stdio MCP 服务。

此二进制程序面向 Claude Code 和 OpenCode 等编码 Agent，它们可以启动本地 MCP 服务进程，并通过 stdio 调用工具。

提供的功能

当前服务仅提供请求/响应工具：

• bdp - 参考数据
• bdh - 历史数据
• bds - 批量数据
• bdib - 日内柱状数据
• bql - Bloomberg Query Language
• bsrch - Bloomberg 搜索
• bflds - 字段元数据查询
• resolve_venues - 将复合股票及优先股输入解析为经过验证的拍卖场所
• auction_snapshot - 主场所拍卖及失衡参考数据
• check_entitlements - 检查 Bloomberg 服务的授权 ID
• delay_status - 此会话中每个代码的延迟/实时状态，可选检查 feed-EID 授权
• request - 通用原始/自定义请求路径

响应以有界的结构化 JSON 返回，并附带 Arrow 架构元数据，方便 Agent 检查数据形状，而无需接收无界负载。限制涵盖行数、单元格数、字符串长度、元数据检查/保留量以及最终序列化负载；仅限制行数并不能限制输出大小。

拍卖场所和快照

resolve_venues 会将复合股票代码或 ISIN 路由到其主要交易所上市地，并将优先股路由到场所定价源。显式指定的交易所上市地会得到尊重。该配方会为每个输入保留一行，包括重复项和输入顺序，并包含 status（resolved、unresolved、unsupported 或 mismatch）和 error。结果还包含查询值、证券 kind、股票 composite 代码、场所主题、场所 FIGI、路由方法、交易所、MIC 和定价源。security 中会保留原始输入字符串；查询值会去除首尾空格，裸的有效 ISIN 会转换为 /isin/<ISIN>。

{
  "securities": ["IBM US Equity", "AAPL US Equity"],
  "pcs_overrides": {"NEW YORK": "SNY2"}
}

两个工具都可以选择性地使用 pcs_overrides。其键为首选交易所名称，会去除首尾空格、转换为大写，并将连续的内部空格合并为一个；值为去除首尾空格并转换为大写的定价源代码。覆盖项优先于内置映射；空代码或 N.A. 之类的缺失值代码会禁用该交易所的映射。若同一规范化交易所键对应多个拼写形式，则会被拒绝。每条路由在报告为已解析之前都会经过验证；未知的首选交易所需要有对应的 pcs_overrides 条目。

auction_snapshot 会先解析场所，然后使用 Bloomberg 参考数据在该场所读取请求的字段。失败或不匹配的输入会保留其状态和错误行，数据字段为 null。结果包含 input_order、security、venue_topic、status、error，后接所选的类型化字段。

{
  "securities": ["IBM US Equity", "AAPL US Equity"],
  "groups": ["imbalance", "quotes"],
  "fields": ["IN_AUCTION_RT"]
}

可选的 groups 列表接受 imbalance、indicative、state、halts、results、composite、quotes 和 default（会去除首尾空格，且不区分大小写）。系统会按提供的顺序展开各组，然后按提供的顺序处理显式指定的 fields；字段名称会去除首尾空格并转换为大写，重复项会被移除且保留首次出现的项。未知组属于无效参数。如果合并后的选择为空，则使用默认拍卖组，依次为 imbalance、indicative、state、halts 和 results。显式字段或组会替代隐式默认值；若要扩展默认值，请在 groups 中加入 default。

两个工具都要求至少提供一个非空白证券（数量不限；结果受输出限制约束），且最多接受 128 个定价源覆盖项。auction_snapshot 最多接受 8 个组条目、256 个显式字段，以及展开后 256 个不重复字段。每个输入字符串（包括覆盖项的键和值）都不得超过 1,024 个 UTF-8 字节；空白证券、字段、组名称或覆盖项键会被拒绝，而不会被静默丢弃。允许使用空白覆盖项值来禁用映射。

时间和延迟状态： 时刻字段采用终端本地时间，而非交易所本地时间。Bloomberg 可以提供延迟值，但不会在行中标记这些值。本会话的延迟标志可通过 delay_status、bdp、bdh、bdib 和 request 中的 on_delayed 获取，也可以通过 bdp 请求 IS_DELAYED_STREAM 和 EXCHANGE_DELAY 获取；请参阅延迟数据。

时间类型单元格遵循现有的 Arrow JSON 字符串约定：Date32 格式为 YYYY-MM-DD，Time64 格式为 HH:MM:SS[.fraction]，不会凭空添加日期或时区。时间戳同时包含日期和时间；UTC 时间以 Z 结尾，其他已声明时区会包含其偏移量，无时区的时间戳则不带后缀。小数秒会原样保留，不进行舍入；拍卖快照中的微秒也会保留。空单元格仍为 JSON null。相同的序列化规则也适用于类型化请求列，例如 value_time 和 value_ts；Arrow 架构会保留原始时间类型、单位和时区。

两个工具都使用与 bdp 相同的有界 JSON 封装，并附带 Arrow 架构元数据。结果限制可能会省略行或字段；在将返回行视为完整输入集之前，请务必检查截断标志和计数。

Entitlement ID

仅在由支持 returnEids 的 Bloomberg 操作提供支持的路由上设置 return_eids: true：

MCP 路由	Bloomberg 操作	EID 选项
bdp、bds	ReferenceDataRequest（包括 BDS/批量请求）	return_eids: true
bdh	HistoricalDataRequest	return_eids: true
bdib	IntradayBarRequest	return_eids: true
request	IntradayTickRequest	return_eids: true

专用的 bdp、bds、bdh 和 bdib 工具会直接提供 return_eids 选项。对于日内 tick，请使用通用的 request 工具：

{
  "service": "//blp/refdata",
  "operation": "IntradayTickRequest",
  "extractor": "intraday_tick",
  "security": "AAPL US Equity",
  "start_datetime": "2024-01-15T09:30:00",
  "end_datetime": "2024-01-15T10:00:00",
  "event_types": ["TRADE"],
  "return_eids": true
}

在元数据和输出预算范围内保留时，结果会在 metadata["xbbg.eid_data"] 中以结构化 JSON 的形式提供 EID 映射，以及 schema、row_count、returned_rows、truncated 和 rows。truncated 是一个标志对象，而非单个布尔值。如果存在，请参阅 metadata_counts["xbbg.eid_data"]，了解 EID 和证券的总数与返回数量、valid 以及 counts_complete；未知总数为 null，而非零。truncation_counts.omitted_priority_metadata 表示未能保留的优先级元数据。将收集到的 ID 传递给只读的 check_entitlements 工具；service 默认值为 //blp/refdata：

{ "eids": [101, 202], "service": "//blp/refdata" }

检查结果包含 service、eids、entitled 和 failed_eids，以及两组 ID 列表的总数、返回数量和省略数量，以及各组件的 truncated 标志。失败的 ID 会与回显的输入 ID 共用单元格/字节额度。不得将缩短后的列表解读为完整的授权检查结果。

延迟数据

Bloomberg 提供延迟数据，但不会标记这些行：延迟的 bdp 快照、bdh 返回的延迟“今日”行，以及截止时间为当前时间减去延迟时长的日内柱线或逐笔数据。IS_DELAYED_STREAM 是请求会话的延迟标志。EXCHANGE_DELAY 是交易所的标准延迟时长，以文本形式表示，例如 15 Minutes；即使是实时证券也会设置此字段。

delay_status 在一次参考数据请求中读取这两个字段、EXCH_CODE 和 feed EID，并按输入顺序为每个唯一股票代码返回一行：

{ "tickers": ["VOD LN Equity", "AAPL US Equity"], "check_identity": false }

列	含义
ticker	请求的证券
delayed	此会话接收的是延迟数据（IS_DELAYED_STREAM）；未知时为 null
delay_minutes	根据 EXCHANGE_DELAY 解析出的落后实时数据分钟数；实时或未知时为 null
exchange_delay	原始 EXCHANGE_DELAY 文本
exch_code	EXCH_CODE
realtime_eid1 至 realtime_eid4	实时 feed EID FEED_EID1 至 FEED_EID4；Bloomberg 未返回时为 null
delayed_eid	延迟 feed EID FEED_DELAYED_EID1；不存在时为 null
realtime_entitled	会话身份有权使用所有实时 feed EID；仅当设置了 check_identity 且该股票代码至少有一个 EID 时才有值，否则为 null
delayed_entitled	会话身份有权使用 delayed_eid；仅当设置了 check_identity 且该 EID 存在时才有值，否则为 null
error	Bloomberg 证券错误消息；否则为 null

check_identity 默认为 false，适用于任何 Desktop Terminal。将其设为 true 后，还会针对 //blp/mktdata 检查所有返回的 feed EID 的权限，并将失败项映射回各个股票代码。这需要已授权的身份：通过 XBBG_MCP_AUTH_METHOD 配置的 SAPI/B-PIPE 授权（参见运行环境），或已加入 EMRS 的 Desktop API 用户。否则调用会失败。

on_delayed 会在 bdp、bdh、bdib 和通用 request 工具（ReferenceDataRequest、HistoricalDataRequest、IntradayBarRequest 或 IntradayTickRequest）的数据请求旁执行相同检查。bds 不支持此选项；通用 request 工具在任何其他操作中（包括 BDS/批量操作）都会将其作为无效参数拒绝。

• bdp 会将你未请求的 IS_DELAYED_STREAM 和 EXCHANGE_DELAY 字段添加到同一请求中；这些新增字段不会作为行返回。
• bdh、bdib 和日内逐笔请求只会在时间窗口涵盖最近 24 小时时发送一个额外的小型参考数据请求：end_date 不早于昨天（UTC），或 end_datetime 不早于 24 小时前。更早的时间窗口会跳过检查，不添加元数据。

on_delayed	结果
省略	不进行检查
warn	数据，以及 metadata["xbbg.delayed"]
ignore	数据，以及 metadata["xbbg.delayed"]
raise	调用失败，错误中包含 Bloomberg is delivering delayed data; on_delayed=raise 以及延迟的股票代码

MCP 结果没有警告通道，因此 warn 和 ignore 在此处行为相同：请检查元数据。元数据以股票代码为键；Bloomberg 未返回标志的股票代码（无效证券或不适用该字段）不会出现：

{
  "VOD LN Equity": { "delayed": true, "delay_minutes": 15 },
  "AAPL US Equity": { "delayed": false, "delay_minutes": null }
}

xbbg.delayed 是优先级元数据：metadata_counts["xbbg.delayed"] 会报告已返回和省略的属性；如果无法保留，truncation_counts.omitted_priority_metadata 会列出它。

从 GitHub Releases 安装

对于 macOS arm64 和 Linux amd64，使用以下命令安装最新的包装器 + 二进制文件组合：

curl -fsSL https://raw.githubusercontent.com/underloam/xbbg/main/scripts/install-xbbg-mcp.sh | sh

安装特定版本：

curl -fsSL https://raw.githubusercontent.com/underloam/xbbg/main/scripts/install-xbbg-mcp.sh | sh -s -- 1.0.0

安装程序默认会在 ~/.local/bin/ 中放置两个文件：

• xbbg-mcp - 启动器包装器
• xbbg-mcp-real - 编译后的二进制文件

GitHub Release 资源仅包含启动器包装器和编译后的 xbbg 二进制文件，不包含 Bloomberg SDK 文件或 Bloomberg 运行时。你必须从根据 Bloomberg 协议和授权有权使用的来源，在本地提供这些文件。

GitHub Release 的 tar/zip 资源仍是原始二进制文件渠道。MCPB 资源则是供支持 MCPB 的客户端和注册表使用的目录及一键式本地连接器渠道。

包装器按以下顺序查找 Bloomberg 运行时：

1. XBBG_MCP_LIB_DIR
2. BLPAPI_LIB_DIR
3. BLPAPI_ROOT
4. vendor/blpapi-sdk/ 下本地暂存的授权 SDK
5. 官方 Python blpapi 包

如果安装 Bloomberg 的 Python 包，通常无需额外配置 shell，包装器即可运行：

pip install blpapi --index-url https://blpapi.bloomberg.com/repository/releases/python/simple/

Windows 发布资源以 .zip 文件形式附加，但便捷安装程序目前仅适用于 macOS/Linux。

安装 MCPB

Claude Desktop 和支持 MCPB 的注册表可使用 GitHub Releases 中附带的 xbbg-mcp-v<VERSION>.mcpb 资源。MCPB 目前支持 macOS arm64、Linux amd64 和 Windows amd64。原始平台 tar/zip 资源仍可用于手动安装和故障排查。

MCPB 不包含 Bloomberg SDK 文件、Bloomberg 运行时库、凭据或市场数据。请配置 XBBG_MCP_LIB_DIR、BLPAPI_LIB_DIR、BLPAPI_ROOT，或安装 Bloomberg 官方 Python blpapi 包，以便启动器在本地找到经授权的 Bloomberg 运行时。

在 Windows 上，MCPB PowerShell 启动器遵循相同的查找顺序，随后还会扫描 PATH（Bloomberg Terminal 安装程序会将 C:\blp\DAPI 添加到其中），最后才回退到 Python 包。xbbg-mcp.exe 是 64 位程序，需要 blpapi3_64.dll；如果无法读取运行时版本，或运行时版本过旧、无法导出该二进制文件导入的入口点，启动器会跳过它并显示诊断信息。当前最低版本 Bloomberg API 3.20.0 是在打包时根据导入的符号版本推导得出的；如果无法推导，打包会失败，而不会静默禁用此检查。启动器会将通过验证的目录同时设为子进程的工作目录和 PATH 中的首个条目，并拒绝使用可执行文件旁或 Windows 系统目录中优先级更高、会遮蔽该目录的 DLL。启动器会以继承的标准句柄启动 xbbg-mcp.exe，因此 MCP 主机直接与二进制文件通信，而不是通过 PowerShell。加载器状态诊断会指出所选的 Bloomberg 运行时，但不会声称它导致了每一种直接或传递的加载器故障。

故障排查

服务器只向 stderr 写入内容，Claude Desktop 等 MCP 主机会将其捕获到服务器日志中。主机关闭 stdin 时，服务器会打印 xbbg-mcp: stdin closed; shutting down；如果 stdin 读取失败、读取线程失败或服务异常停止，进程会返回非零状态码。诊断信息的写入采用尽力而为的方式，因此关闭的 stderr 句柄不会终止 stdin 读取线程，也不会将故障变为正常 EOF。设置 RUST_LOG=info（或 debug）还可查看引擎和 MCP 库自身的日志行。

从源代码构建

bash ./scripts/sdktool.sh
cargo build --release -p xbbg-mcp --locked
./scripts/xbbg-mcp

Claude Code

claude mcp add --transport stdio xbbg -- ~/.local/bin/xbbg-mcp

OpenCode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "xbbg": {
      "type": "local",
      "command": ["/Users/you/.local/bin/xbbg-mcp"],
      "enabled": true
    }
  }
}

目录与注册表发布

官方 MCP 注册表：发布生成的 server.json，并确保发行包中包含 .mcpb 资源。

GitHub MCP 注册表：官方注册表完成收录后，确认服务已显示。

Claude Connectors Directory：将 MCPB 作为桌面扩展提交；远程连接器并非 Bloomberg 本地工作流的默认选项。

Smithery：发布 MCPB 捆绑包。

Glama：官方注册表发布后，确认已建立索引；如果自动沙盒构建无法在没有 Bloomberg 运行时的情况下运行，则保持列表信息以元数据为主。

PulseMCP：等待官方注册表完成收录，或使用 Pulse 提交页面。

MCP.so：规范注册表元数据上线后，提交 GitHub 仓库或发行包。

运行时环境

xbbg-mcp 接受与 Rust 核心相同的面向引擎的连接设置；如果存在 MCP 前缀名称，则优先使用。

常用设置：

• XBBG_MCP_HOST / XBBG_HOST
• XBBG_MCP_PORT / XBBG_PORT
• XBBG_MCP_AUTH_METHOD / XBBG_AUTH_METHOD
• XBBG_MCP_APP_NAME
• XBBG_MCP_BQL_APP_NAME – 可选的共享引擎 BQL 客户端上下文默认值；与会话身份验证相互独立
• XBBG_MCP_DIR_PROPERTY
• XBBG_MCP_USER_ID
• XBBG_MCP_IP_ADDRESS
• XBBG_MCP_TOKEN
• XBBG_MCP_REQUEST_POOL_SIZE
• XBBG_MCP_VALIDATION_MODE / XBBG_VALIDATION_MODE – disabled（默认）、lenient、strict
• XBBG_MCP_SDK_LOG_LEVEL / XBBG_SDK_LOG_LEVEL – off（默认）、fatal、error、warn、info、debug、trace
• XBBG_MCP_OVERFLOW_POLICY / XBBG_OVERFLOW_POLICY – drop_newest（默认）、block

支持的身份验证方法：

• none
• user
• app
• userapp
• dir
• directory
• manual
• token

BQL 客户端上下文

共享的 Rust 引擎负责管理可选的 BQL 应用程序名称默认值。 XBBG_MCP_BQL_APP_NAME 会为此服务分发的每个 BQL sendQuery 设置 EngineConfig.bql_app_name，包括通用 request 工具。 bql 工具的单次调用 app_name，以及显式的 clientContext.appName 元素或 kwargs，都会覆盖引擎默认值。如果未提供任何值，则会省略应用程序名称，保持当前 Bloomberg 默认值不变；不会自动选择名称。

{
  "expression": "get(name()) for('IBM US Equity')",
  "app_name": "example-authorized-bql-app"
}

请使用在你的 Bloomberg 环境中获授权的应用程序名称。此设置不会授予 BQL 权限，也不会更改会话身份验证。 XBBG_MCP_APP_NAME 仍是身份验证设置，而非 BQL 客户端上下文设置。显式留空的单次调用 app_name 会被拒绝，不会回退到服务的应用程序名称。

SDK 的应用程序模式身份验证和应用程序身份密钥是独立的会话设置。BQL 默认值是请求元素，不会设置 SDK 身份验证或会话标识选项。

通用 request 工具也接受 clientContext.appName 作为字符串值 elements 映射中的点分隔键；该映射不接受嵌套对象。

致命的 BQL 响应异常会连同服务和操作上下文保留在 MCP 错误消息中。消息仍受以下字符串和序列化输出预算的限制；被缩短的错误会包含 message_truncated: true。

结果预算

这些仅适用于 MCP 的环境设置使用整数值；未设置的选项使用下表中的默认值。低于最小值的值或无效整数会导致配置失败，而不是静默禁用限制。

设置	默认值	最小值	范围
XBBG_MCP_MAX_ROWS	500	1	返回的行
XBBG_MCP_MAX_CELLS	50,000	1	返回的单元格和检查的架构列；也适用于共享的授权列表项和验证错误记录数
XBBG_MCP_MAX_METADATA_PROPERTIES	50,000	1	保留的元数据属性／数组项总数以及元数据条目检查
XBBG_MCP_MAX_METADATA_BYTES	65,536	1	解析前检查的原始元数据总字节数，以及保留的元数据及其计数摘要
XBBG_MCP_MAX_STRING_CHARS	2,048	1	每个字符串的 Unicode 字符数
XBBG_MCP_MAX_STRING_BYTES	8,192	3	每个字符串的 UTF-8 字节数；必要时包括截断标记
XBBG_MCP_MAX_RESULT_BYTES	1,048,576	2,048	最终序列化的结构化 JSON 负载，包括架构、元数据和诊断信息；也限制序列化后的错误结果

最终字节数上限包括 JSON 转义和封装开销；它并非原始字符串长度的简单总和，也不涵盖外层 MCP 传输帧。各项限制都是上限：元数据和架构会先占用空间，因此负载返回的行数或列数可能少于各自限制所允许的数量。单元格限额适用于返回的行和列总数，而非每一行单独计算。即使批次包含零行，架构输出也有上限。

字符串值会按 Unicode 边界缩短。列名和元数据键是标识符：超长名称会被省略，而不会缩短；JSON 行中的重复列名也不会被静默覆盖。嵌套 Arrow 值会以有界的省略标记表示，而不会递归格式化无界单元格；省略计数可将此情况与普通标量值区分开来。超出 JavaScript 安全范围的整数值会以字符串而非经过舍入的数字返回。

元数据检查在 JSON 解析前受到限制。超大条目以及无法在总限额内检查的通用元数据可能会被省略，而无需完整扫描。xbbg.security_errors、xbbg.field_exceptions、xbbg.delayed 和 xbbg.eid_data 的优先级高于通用元数据和行。诊断记录会保留其结构，而不是任意的属性片段，但字符串内容和记录数仍受限制；即使是优先元数据，如果无法放入负载，也可能被省略。

输出诊断信息和错误

结果信封可扩展。例如，单行结果可以包含以下摘录（此处省略其他计数器）：

{
  "schema": [{ "name": "PX_LAST", "data_type": "Float64", "nullable": true }],
  "row_count": 1,
  "column_count": 1,
  "returned_rows": 1,
  "returned_columns": 1,
  "returned_cells": 1,
  "result_budget_bytes": 1048576,
  "truncated": {
    "rows": false,
    "columns": false,
    "cells": false,
    "values": false,
    "metadata": false,
    "output": false
  },
  "rows": [{ "PX_LAST": 190.1 }]
}

row_count 和 column_count 描述源批次；returned_* 字段描述实际输出的内容。truncation_counts 报告省略情况和检查完整性，包括 omitted_rows、omitted_columns、omitted_cells、known_omitted_value_bytes、omitted_complex_values 和 known_omitted_metadata_properties。除非已确认完整性，否则应将 known_* 计数视为下限，而不是穷尽扫描的证据。具体而言，schema_column_count_complete、metadata_input_count_complete 和 metadata_property_count_complete 用于限定相关诊断信息；当输入计数不完整时，omitted_metadata_input_bytes 为 null。可选的 metadata_counts 提供额外的逐键诊断信息。

错误也有大小限制：请求、验证和内部故障仍会作为错误返回，而不是伪装成成功的空结果。错误消息遵守字符串和转义 JSON 的字节数限制；message_truncated 表示消息已缩短。现有适配器错误代码会保留，而省略的辅助错误数据会通过 error_data_omitted 标记。验证错误会返回有大小限制的结构化 errors 记录，其中包含 path、message 和逐条记录的 truncated 标记，以及 total_errors、returned_errors 和 omitted_errors。即使结果预算最低为 2,048 字节，也会为主要验证诊断信息预留空间：其路径和消息优先于较长的摘要或可选的 suggestion。路径和消息可能会缩短，建议或后续记录可能会被省略，但后续错误不会取代主要诊断信息。

序列化并发

该服务使用两个异步运行时工作线程。小型结果转换会内联执行；较大或开销较高的转换会转交给阻塞工作线程。共享许可限制最多允许同时进行两项转交的序列化操作，且许可会一直持有到转换完成。这限制的是序列化并发数，而非进程线程总数：Bloomberg 引擎工作和标准输入输出处理有各自的生命周期。

隐私政策

xbbg-mcp 在本地以标准输入输出 MCP 服务的形式运行。它不会向 underloam、GitHub、Anthropic、Smithery、Glama 或任何其他第三方发送遥测数据或使用数据。

工具调用在用户的计算机上处理，并且只会转发到用户配置的 Bloomberg 运行时/API 端点（XBBG_MCP_HOST / XBBG_HOST，默认为 localhost:8194），并遵守用户的 Bloomberg 协议和授权。结果仅返回给启动该服务的 MCP 客户端进程。

Bloomberg 会在请求时验证授权，包括对每种证券和每个字段的访问权限。即使本地会话有效，如果用户的 DAPI、SAPI/B-PIPE 或 ZFP 授权范围未涵盖所请求的数据，仍可能返回空结果或部分结果。

该服务从环境变量读取配置，不会将请求数据、凭据或 Bloomberg 响应持久化到磁盘。

冒烟测试

在本地构建后，使用以下命令验证标准输入输出握手并执行几个实时请求：

uv run python -X utf8 scripts/xbbg_mcp_smoke.py

该脚本需要连接到实时 Bloomberg，并且需要存在本地构建的 target/debug/xbbg-mcp 二进制文件；如果没有 debug 构建，则使用 target/release/xbbg-mcp。