xbbg MCP

xbbg-mcp

Last updated: 2026-10-20.

Stdio MCP server for Bloomberg request/response workflows backed by xbbg-async.

This binary is intended for coding agents such as Claude Code and OpenCode that can launch a local MCP server process and call tools over stdio.

What it exposes

The current server exposes request/response tools only:

• bdp - reference data
• bdh - historical data
• bds - bulk data
• bdib - intraday bars
• bql - Bloomberg Query Language
• bsrch - Bloomberg search
• bflds - field metadata lookup
• resolve_venues - resolve composite equity and preferred inputs to validated auction venues
• auction_snapshot - primary-venue auction and imbalance reference data
• check_entitlements - entitlement-ID check for a Bloomberg service
• delay_status - per-ticker delayed/real-time status for this session, with an optional feed-EID entitlement check
• request - generic raw/custom request path

Responses are returned as bounded structured JSON with Arrow schema metadata so an agent can inspect the shape without receiving an unbounded payload. Limits cover rows, cells, strings, metadata inspection/retention, and the final serialized payload; a row limit alone is not the output bound.

Auction venues and snapshots

resolve_venues routes composite equity tickers or ISINs to their primary exchange listing and preferreds to venue pricing sources. Explicit exchange listings are respected. The recipe keeps one row per input, including duplicates and input order, with status (resolved, unresolved, unsupported, or mismatch) and error. The result also includes the lookup, security kind, equity composite ticker, venue topic, venue FIGI, routing method, exchange, MIC, and pricing source. Original input strings are retained in security; lookups are trimmed, and bare valid ISINs become /isin/ .

{

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

pcs_overrides is optional on both tools. Its keys are preferred exchange names, trimmed, uppercased, and collapsed to single internal spaces; values are trimmed and uppercased pricing-source codes. Overrides take precedence over the built-in mapping; a blank or missing-value code such as N.A. disables the mapping for that exchange. Conflicting spellings of the same normalized exchange key are rejected. Every route is validated before it can be reported as resolved; an unknown preferred exchange needs a pcs_overrides entry.

auction_snapshot first resolves the venue, then reads the requested fields using Bloomberg reference data on that venue. Failed or mismatched inputs retain their status/error row with null data fields. Results contain input_order, security, venue_topic, status, error, then the selected typed fields.

{

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

The optional groups list accepts imbalance, indicative, state, halts, results, composite, quotes, and default (trimmed, case-insensitive). Groups expand in the supplied order, followed by the explicit fields in their supplied order; field names are trimmed and uppercased and duplicates are removed, keeping their first occurrence. Unknown groups are invalid parameters. If the combined selection is empty, the default auction group is used: imbalance, indicative, state, halts, and results, in that order. Explicit fields or groups replace that implicit default; include default in groups to extend it.

Both tools require at least one nonblank security (there is no count limit; results are bounded by the output limits) and accept at most 128 pricing-source overrides. auction_snapshot accepts up to eight group entries, 256 explicit fields, and 256 unique fields after expansion. Every input string, including override keys and values, is limited to 1,024 UTF-8 bytes; blank securities, fields, group names, or override keys are rejected rather than silently dropped. Blank override values are allowed to disable a mapping.

Timing and delayedness: time-of-day fields are terminal-local, not exchange-local. Bloomberg can serve delayed values without marking them in the rows. The delayed flag for this session is available from delay_status, from on_delayed on bdp, bdh, bdib, and request, or by requesting IS_DELAYED_STREAM and EXCHANGE_DELAY with bdp; see Delayed data.

Temporal cells use the existing Arrow JSON string conventions: Date32 is YYYY-MM-DD, and Time64 is HH:MM:SS[.fraction] without an invented date or timezone. Timestamps include both date and time; UTC ends in Z, other declared timezones include their offset, and timestamps without a timezone have no suffix. Fractional seconds are preserved without rounding, including the microseconds in auction snapshots. Null cells remain JSON null. The same serialization applies to typed request columns such as value_time and value_ts; the Arrow schema retains the original temporal type, unit, and timezone.

Both tools use the same bounded JSON envelope with Arrow schema metadata as bdp. Result limits can omit rows or fields; always inspect the truncation flags and counts before treating the returned rows as the complete input set.

Entitlement IDs

Set return_eids: true only on routes backed by Bloomberg operations that support returnEids:

The dedicated bdp, bds, bdh, and bdib tools advertise return_eids directly. Use the generic request tool for intraday ticks:

{

"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 }

When retained within the metadata and output budgets, results expose the EID map as structured JSON at metadata["xbbg.eid_data"], alongside schema, row_count, returned_rows, truncated, and rows. truncated is an object of flags, not a single boolean. Consult metadata_counts["xbbg.eid_data"] when present for total/returned EID and security counts, valid, and counts_complete; an unknown total is null, not zero. truncation_counts.omitted_priority_metadata identifies priority metadata that could not be retained. Pass the collected IDs to the read-only check_entitlements tool; service defaults to //blp/refdata:

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

The check result includes service, eids, entitled, and failed_eids, plus total, returned, and omitted counts for both ID lists and per-component truncated flags. Failed IDs receive the shared cell/byte allowance before the echoed input IDs. A shortened list must not be interpreted as the full entitlement result.

Delayed data

Bloomberg serves delayed data without marking the rows: a delayed bdp snapshot, a delayed "today" row from bdh, and intraday bars or ticks that stop at the current time minus the delay. IS_DELAYED_STREAM is the delayed flag for the requesting session. EXCHANGE_DELAY is the exchange's standard delay as text, such as 15 Minutes, and is set for real-time securities too.

delay_status reads both fields, EXCH_CODE, and the feed EIDs in one reference-data request and returns one row per unique ticker, in input order:

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

check_identity defaults to false, which works on any Desktop Terminal. Setting it to true also runs one entitlement check of all returned feed EIDs against //blp/mktdata and maps the failures back to each ticker. That needs an authorized identity: SAPI/B-PIPE authorization configured through XBBG_MCP_AUTH_METHOD (see Runtime environment), or a Desktop API user enrolled in EMRS. Otherwise the call fails.

on_delayed runs the same check alongside a data request on bdp, bdh, bdib, and the generic request tool (ReferenceDataRequest, HistoricalDataRequest, IntradayBarRequest, or IntradayTickRequest). bds does not offer it, and the generic request tool rejects it as an invalid parameter for any other operation, including BDS/bulk.

• bdp adds whichever of IS_DELAYED_STREAM and EXCHANGE_DELAY you did not request to the same request; the added fields are not returned as rows.
• bdh, bdib, and intraday-tick requests send one extra small reference-data request, only when the window reaches the last 24 hours: end_date on or after yesterday (UTC), or end_datetime no earlier than 24 hours ago. Older windows skip the check and add no metadata.

MCP results have no warnings channel, so warn and ignore behave the same here: inspect the metadata. It is keyed by ticker; tickers whose flag Bloomberg did not return (an invalid security, or a field that does not apply) are absent:

{

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

xbbg.delayed is priority metadata: metadata_counts["xbbg.delayed"] reports returned and omitted properties, and truncation_counts.omitted_priority_metadata lists it if it could not be retained.

Install from GitHub Releases

For macOS arm64 and Linux amd64, install the latest wrapper + binary pair with:

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

To install a specific release:

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

The installer places two files in ~/.local/bin/ by default:

• xbbg-mcp - launcher wrapper
• xbbg-mcp-real - compiled binary

GitHub release assets include only the launcher wrapper and compiled xbbg binary. They do not include Bloomberg SDK files or the Bloomberg runtime. You must provide those locally from a source you are authorized to use under your Bloomberg agreements and entitlements.

GitHub Release tar/zip assets remain the raw binary channel. The MCPB asset is the directory and one-click local connector channel for MCPB-aware clients and registries.

The wrapper locates the Bloomberg runtime in this order:

1. XBBG_MCP_LIB_DIR
2. BLPAPI_LIB_DIR
3. BLPAPI_ROOT
4. locally stage