xbbg-mcp

Python JavaScript Rust

Links: Documentation · Quickstart · Configuration · Examples notebook · Contributing · Changelog

---

Latest release: xbbg==1.4.12 (release: notes)

This main branch is the Rust-powered v1 release. For the legacy pure-Python line, use release/0.x.

Important: xbbg is an independent open-source project. It is not affiliated with, endorsed by, sponsored by, or approved by Bloomberg Finance L.P. or its affiliates. Bloomberg, Bloomberg Terminal, B-PIPE, BQL, and related names are trademarks or service marks of their respective owners. xbbg does not grant access to Bloomberg services, data, software, licenses, credentials, or entitlements; users must obtain and use those separately under their own Bloomberg agreements and applicable policies.

Contents

• What is xbbg?
• Why xbbg?
• Installation
• Quickstart
• JavaScript and Node
• Configuration and engines
• Common API surface
• Entitlement IDs
• Output backends
• Async usage
• Subscriptions: raw, tick mode, and all fields
• MCP server
• Troubleshooting
• Development
• Project links

What is xbbg?

xbbg is a Bloomberg client with Python as the primary surface and companion JavaScript/Node bindings, all backed by a shared Rust engine for request execution, response parsing, Arrow-shaped data movement, async workers, typed errors, and diagnostics.

Use xbbg when you already have Bloomberg access and want higher-level helpers for common request patterns, plus an escape hatch for lower-level Bloomberg service requests.

Core scope:

• request helpers for BDP, BDS, BDH, intraday bars, ticks, BQL, BEQS, BSRCH, BQR, BTA, YAS, and related analytics
• local Bloomberg Desktop API / DAPI by default
• configuration for managed Bloomberg environments, including B-PIPE/SAPI, ZFP leased lines, TLS, failover hosts, SOCKS5, and SDK logging
• sync and async Python APIs backed by the same engine
• output as Narwhals, native xbbg Arrow carriers, PyArrow, pandas, Polars, DuckDB, and other optional Narwhals-backed libraries
• JavaScript/Node bindings in js-xbbg

Why xbbg?

xbbg's project goal is direct: be the most complete, technically advanced, and performance-focused open-source Bloomberg client for Python workflows, while staying independent of Bloomberg and requiring users to bring their own authorized Bloomberg access.

The short version: if all you need is a tiny one-off bdp() wrapper, several packages can work. xbbg is built for the path where that notebook later grows into intraday data, BQL, streaming, B-PIPE/SAPI, ZFP, async services, typed errors, diagnostics, and non-pandas data pipelines.

Capability	xbbg	raw blpapi	pdblp / blp	bbg-fetch	polars-bloomberg
BDP/BDS/BDH helpers	yes	manual SDK code	yes	yes	partial
Intraday bars and ticks	yes	manual SDK code	limited / no	no	partial
Streaming subscriptions	yes	manual SDK code	no	no	no
BQL, BEQS, BSRCH, BQR, YAS, BTA	broad helper coverage	manual SDK code	limited	limited	partial
DAPI, SAPI/B-PIPE, ZFP, TLS, failover, SOCKS5	configurable engine support	manual SDK code	limited	limited	limited
Async worker pools and isolated subscription sessions	yes	application-owned	no	no	no
Rust request/parsing engine with Arrow-shaped output	yes	no	no	no	no
Output backends beyond pandas	Narwhals, native, PyArrow, pandas, Polars, DuckDB	application-owned	pandas-first	pandas-first	Polars-first
Typed errors, diagnostics, field cache, testing helpers	yes	application-owned	limited	limited	limited
Usable install footprint (Windows x64, Python 3.14)	xbbg 1.4.12 + narwhals 2.26.0, no blpapi = 18.245 MiB	blpapi 3.26.8.1 = 14.702 MiB	pdblp 0.1.8 + pandas 3.0.5 + numpy 2.5.3 + blpapi 3.26.8.1 = 130.816 MiB / blp 0.0.4 + pandas 3.0.5 + numpy 2.5.3 + blpapi 3.26.8.1 = 131.002 MiB	bbg-fetch 3.2.0 + pandas 3.0.5 + numpy 2.5.3 + blpapi 3.26.8.1 = 130.863 MiB	polars-bloomberg 0.6.0 + polars 1.44.2 + blpapi 3.26.8.1 = 191.118 MiB

Installation

pip install xbbg

Conda users can install the conda-forge build:

conda install -c conda-forge xbbg

blpapi is not required as a Python dependency. xbbg only needs Bloomberg's shared runtime library (blpapi3_64.dll on Windows, libblpapi3_64.so on macOS/Linux), which can come from Bloomberg Terminal/DAPI, a managed Bloomberg C++ SDK install, or Bloomberg's official blpapi wheel. Installing the wheel is just the easiest discovery path for many users:

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

Supported Python versions: 3.10 through 3.14.

Requirements and notes:

• You need an authorized Bloomberg environment: local Terminal/DAPI, SAPI/B-PIPE, or ZFP, depending on your setup.
• If you build from source, stage the Bloomberg C++ SDK with bash ./scripts/sdktool.sh on macOS/Linux or .\\scripts\\sdktool.ps1 on Windows PowerShell.
• If you manage the SDK yourself, set BLPAPI_ROOT or use xbbg.set_sdk_path(...).
• On Windows Terminal installs, xbbg automatically probes DAPI runtime roots such as C:\blp\DAPI and C:\Program Files (x86)\Bloomberg\Blp\DAPI before requiring manual configuration.
• Linux wheels are manylinux_2_28 (x86_64): any distro with glibc ≥ 2.28 works — RHEL/Alma/Rocky 8+, Debian 10+, Ubuntu 20.04+, Amazon Linux 2023.
• Optional dataframe conversions are installed separately: xbbg[pyarrow], xbbg[pandas], xbbg[polars], or xbbg[duckdb].

Verify the install:

import xbbg

print(xbbg.__version__)
print(xbbg.get_sdk_info())

Quickstart

from xbbg import blp

# Reference data
prices = blp.bdp(["AAPL US Equity", "MSFT US Equity"], "PX_LAST")

# Historical data
hist = blp.bdh("SPX Index", "PX_LAST", "2024-01-01", "2024-12-31")

# Intraday bars
bars = blp.bdib("TSLA US Equity", dt="2024-01-15", interval=5)

Common request patterns:

from xbbg import blp, ovr

# Multiple fields
info = blp.bdp("NVDA US Equity", ["Security_Name", "GICS_Sector_Name", "PX_LAST"])

# Bloomberg-style overrides
vwap = blp.bdp("AAPL US Equity", "Eqy_Weighted_Avg_Px", VWAP_Dt="20240115")
adj = blp.bdp("AAPL US Equity", "CRNCY_ADJ_PX_LAST", overrides=ovr(EQY_FUND_CRNCY="EUR"))
per_sec = blp.bdp(
    ["AAPL US Equity", "MSFT US Equity"],
    "CRNCY_ADJ_PX_LAST",
    overrides=ovr(
        {
            "EQY_FUND_CRNCY": "USD",
            "AAPL US Equity": ovr(EQY_FUND_CRNCY="EUR"),
            "MSFT US Equity": ovr(EQY_FUND_CRNCY="JPY"),
        }
    ),
)

# Bulk data
holders = blp.bds("AAPL US Equity", "DVD_Hist_All", DVD_Start_Dt="20240101")

# BQL
result = blp.bql("get(px_last) for('AAPL US Equity')")

# Field lookup
fields = blp.bflds(search_spec="vwap")

# Equity screening and constituents
screen = blp.beqs(screen="MyScreen", asof="2024-01-01")
members = blp.index_members("SPX Index", asof="2024-01-02")

# Workflow helpers
active = blp.active_futures("ESA Index", "2024-01-15")
surface = blp.vol_surface("SPX Index", start_date="2024-01-02", end_date="2024-01-05")
resolved = blp.resolve_isins(["US0378331005", "INVALIDISIN000"])

ETF NAV / iNAV workflows live in xbbg.ext and resolve Bloomberg's authoritative ETF_NAV_TICKER / ETF_INAV_TICKER relationships instead of guessing ticker suffixes:

from xbbg import ext

# Relationship discovery: QQQ US Equity -> QQQNV Index / QXV Index,
# AT1 LN Equity -> null daily NAV / AT1IN Index (independently nullable)
rel = ext.etf_nav_relationships(["QQQ US Equity", "AT1 LN Equity"])

# Daily NAV/iNAV history: mapped Index targets price with PX_LAST; AT1's
# missing daily NAV falls back to the fund's FUND_NET_ASSET_VAL — see the
# nav_source_ticker / nav_source_field columns on every row
hist = ext.etf_nav_history(
    ["QQQ US Equity", "AT1 LN Equity"],
    start_date="2026-06-01",
    end_date="2026-07-01",
)

# Real-time iNAV: validates every mapping first, then subscribes to the
# resolved iNAV topics (here QXV Index) with LAST_PRICE by default
sub = await ext.asubscribe_etf_inav("QQQ US Equity")
async for table in sub:
    print(table.to_pylist())
    break
await sub.unsubscribe()

For longer walkthroughs and example output shapes, use the examples notebook or xbbg.org.

JavaScript and Node

xbbg also ships supported Node bindings in @xbbg/core. The JS layer uses the same Rust engine through a native N-API addon, so Node can use the same Bloomberg connection modes and request surfaces as Python.

npm install @xbbg/core
# or
bun add @xbbg/core

The packages target Node.js 24+ server runtimes. Packaged native addons are provided for macOS arm64, Linux x64 (glibc 2.28+), and Windows x64. You still need Bloomberg access plus Bloomberg SDK runtime libraries on the target system.

import * as xbbg from '@xbbg/core';

xbbg.configure({ host: 'localhost', port: 8194 });

const hist = await xbbg.blp.abdh(['AAPL US Equity'], ['PX_LAST'], '2024-01-01', '2024-12-31');
const ref = await xbbg.blp.abdp(['AAPL US Equity'], ['PX_LAST', 'SECURITY_NAME']);

See js-xbbg/README.md for platform packaging, runtime prerequisites, and the supported JavaScript API surface.

For LangChain and LangGraph agents, use the supported @xbbg/langgraph adapter. It exposes reusable server-side Bloomberg tools backed by @xbbg/core without making MCP, a chat app, or a browser integration the core path:

npm install @xbbg/langgraph @xbbg/core @langchain/core

import { createAllBloombergTools, BLOOMBERG_TOOL_INSTRUCTIONS } from '@xbbg/langgraph';

const tools = createAllBloombergTools({ maxSecurities: 10, maxFields: 10 });

Use the existing apps/xbbg-mcp package only when you specifically need MCP.

Configuration and engines

By default, xbbg starts a Rust-backed engine and connects to local Bloomberg Desktop API / DAPI on localhost:8194. Configure the engine before the first request when you need a different transport, authentication mode, worker count, timeout policy, field cache, or logging behavior.

from xbbg import blp, configure

# Equivalent to the default local Terminal / DAPI path
configure(host="localhost", port=8194)

print(blp.bdp("AAPL US Equity", "PX_LAST"))

Common environments:

Environment	Use when	Configuration shape
Desktop API / DAPI	Local Bloomberg Terminal session	no config, or configure(host="localhost", port=8194)
Direct server / SAPI	Firm-managed Bloomberg server	configure(host="bpipe-host", port=8194, auth_method="app", app_name="...")
B-PIPE	Enterprise Bloomberg feed infrastructure	direct host/failover config plus the auth/TLS settings your Bloomberg setup requires
ZFP leased line	Bloomberg zero-footprint leased-line path	configure(zfp_remote="8194", tls_client_credentials="...", tls_trust_material="...")

Example B-PIPE/SAPI-style configuration:

from xbbg import configure

configure(
    host="bpipe-host",
    port=8194,
    auth_method="app",
    app_name="my-app",
    request_pool_size=4,
    # Opt-in sharding for wide multi-security BDP/BDH requests:
    # shard_requests=True,
    # shard_threshold=20,
    # shard_chunk_size=16,
    # shard_max_concurrent=4,
    subscription_pool_size=2,
    num_start_attempts=5,
)

Example ZFP leased-line configuration:

from xbbg import configure

configure(
    zfp_remote="8194",
    tls_client_credentials="/path/to/client.p12",
    tls_client_credentials_password="<load from your secret store>",
    tls_trust_material="/path/to/trust.pem",
)

The engine uses separate worker pools for request/response calls and subscriptions:

• request workers hold independent Bloomberg sessions and dispatch BDP/BDH/BDS/BQL-style calls across the pool
• subscription sessions are isolated from request workers, so live streams do not share a single blocking session with batch requests
• field validation, field-type caching, SDK logging, retry policy, keep-alive, slow-consumer thresholds, TLS, SOCKS5, and failover servers are configuration options rather than per-call ad hoc code

runtime_worker_threads defaults to 2 (minimum 1) and controls the engine's shared Tokio runtime, not the total process thread count. subscription_pool_size is the pre-warm count (default 1, minimum 0); max_subscription_sessions caps concurrent subscription sessions (default 32, minimum 1, and at least subscription_pool_size). Native subscription admission waits for capacity instead of allocating unbounded sessions. Node uses the corresponding runtimeWorkerThreads, subscriptionPoolSize, and maxSubscriptionSessions fields.

Use Engine(...) when an application needs a scoped engine with its own connection settings instead of mutating global configuration.

Engine shutdown closes subscription admission and signals both idle and checked-out sessions, waking pending operations so termination and errors can reach callers. Close subscriptions explicitly before releasing their engine; do not rely on interpreter teardown for application cleanup.

Field-cache snapshots are published atomically. On Windows this uses FileRenameInfoEx with POSIX rename semantics, requiring Windows 10 1607+ and a supporting filesystem. Existing readers can finish with the old snapshot while new opens see the complete replacement. Unsupported filesystems report persistence errors and retain the prior snapshot; there is no unsafe replacement fallback.

Common API surface

Area	Functions
Reference and bulk data	bdp, bds, bflds, fieldInfo, fieldSearch, blkp, bport
Historical data	bdh, dividend, earnings, turnover, dividend_yield
Intraday data	bdib, bdtick
Query and screening	bql, beqs, bsrch, bqr, bcurves, bgovts, etf_holdings, index_members
Analytics and utilities	yas, bta, ta_studies, ta_study_params, convert_ccy, fut_ticker, active_futures, futures_curve, vol_surface, resolve_isins, issuer_isins, cdx_ticker, active_cdx
Real-time data	subscribe, stream, vwap, mktbar, depth, chains
Generic requests	request, Service, Operation, RequestParams, OutputMode
Schema and diagnostics	bops, bschema, get_sdk_info, enable_sdk_logging, print_backend_status
Testing helpers	xbbg.testing.create_mock_response, xbbg.testing.mock_engine

Most sync helpers have async counterparts with an a prefix: bdp → abdp, bdh → abdh, bdib → abdib, request → arequest.

Entitlement IDs

Bloomberg can return entitlement IDs only for these four request operations. Opt in with return_eids=True:

Bloomberg operation	Python routes
ReferenceDataRequest	blp.bdp, blp.bds (BDS uses the reference-data operation)
HistoricalDataRequest	blp.bdh
IntradayBarRequest	blp.bdib
IntradayTickRequest	blp.bdtick

For example, request EIDs with intraday ticks and check them against the default //blp/refdata service:

from xbbg import blp

ticks = blp.bdtick(
    "AAPL US Equity",
    "2024-01-15T09:30:00",
    "2024-01-15T10:00:00",
    return_eids=True,
    backend="native",
)

eid_data = ticks.eid_data or {}
eids = sorted({eid for security_eids in eid_data.values() for eid in security_eids})
if eids:
    print(blp.check_entitlements(eids))

EID metadata remains available through the native ArrowTable.eid_data property, pandas attrs["xbbg_eid_data"], or PyArrow schema metadata under xbbg.eid_data. Polars and DuckDB do not provide a stable entitlement-metadata side channel; use the native, PyArrow, or pandas backend when EIDs are required.

This opt-in request metadata is separate from a subscription message's top-level EID field.

Output backends

xbbg defaults to a Narwhals DataFrame. When PyArrow is installed, the Narwhals frame is backed by a real pyarrow.Table; otherwise xbbg falls back through available dataframe libraries and finally to its native Arrow carrier.

from xbbg import Backend, blp

# Default Narwhals output
frame = blp.bdh("SPX Index", "PX_LAST", "2024-01-01", "2024-12-31")

# Explicit native xbbg Arrow carrier
table = blp.bdp("AAPL US Equity", "PX_LAST", backend="native")

# Optional conversions
as_pyarrow = blp.bdp("IBM US Equity", "PX_LAST", backend=Backend.PYARROW)
as_pandas = blp.bdp("MSFT US Equity", "PX_LAST", backend=Backend.PANDAS)
as_polars = blp.bdp("AAPL US Equity", "PX_LAST", backend=Backend.POLARS)
as_duckdb = blp.bdh("SPX Index", "PX_LAST", "2024-01-01", "2024-12-31", backend=Backend.DUCKDB)

Output shape is controlled with format=, including long, long_typed, long_metadata, and semi_long.

• Native ArrowTable, ArrowRecordBatch, and ArrowColumn slices can retain their source allocations. Use .compact() when retaining a small result should release that backing storage: it returns an independent copy of the logical values with right-sized buffers, preserving schema, nulls, and physical batch/chunk boundaries. Native zero-column tables retain their row count.
• Polars conversion preserves Arrow chunks rather than implicitly rechunking. The supported floor is Polars >=0.20.4; older supported versions use PyArrow when available or schema-aware per-batch materialization, while capsule-capable versions consume the native Arrow stream. Install xbbg[polars] to include the timezone data required on Windows.
• backend="polars_lazy" returns a Polars LazyFrame; backend="narwhals_lazy" returns a genuine Narwhals lazy frame backed by Polars and requires Polars. Bloomberg retrieval and Arrow-to-Polars conversion have already happened: only subsequent local dataframe operations are deferred, with no Bloomberg query pushdown.
• DuckDB results use isolated per-relation connections to one shared process-local in-memory database, not a new database per conversion. A retained relation keeps its connection and registered Arrow input alive; releasing one relation does not invalidate another. The shared database anchor is closed at process exit. If this backend was initialized before a fork, xbbg refuses inherited backend use or explicit close in the child; use multiprocessing spawn or fork before initializing the DuckDB backend.

Async usage

Use async helpers directly in async applications:

import asyncio
from xbbg import blp

async def main():
    aapl, msft = await asyncio.gather(
        blp.abdp("AAPL US Equity", "PX_LAST"),
        blp.abdp("MSFT US Equity", "PX_LAST"),
    )
    return aapl, msft

result = asyncio.run(main())

In Jupyter, VS Code Interactive, and marimo, one-shot sync calls such as blp.bdp(...) and blp.bdh(...) use a notebook-only bridge when the notebook event loop is already running. Generic async applications such as FastAPI or ASGI services should still use the async APIs directly.

Subscriptions: raw, tick mode, and all fields

Use asubscribe() when you need dynamic add/remove, explicit unsubscribe, raw Arrow batches, or subscription health diagnostics. Use astream() for the simple async iterator, or stream() for synchronous iteration.

from xbbg import asubscribe

sub = await asubscribe(
    ["AAPL US Equity"],
    ["LAST_PRICE", "BID", "ASK"],
    tick_mode=True,
    all_fields=True,
    conflate=True,
)

async for tick in sub:
    print(tick)       # dict ticks in tick_mode
    print(sub.stats)  # messages_received, dropped_batches, data_loss_events, ...
    break

await sub.unsubscribe()

raw_sub = await asubscribe(["AAPL US Equity"], ["LAST_PRICE"], raw=True)

async for batch in raw_sub:
    print(batch.to_table())  # raw xbbg ArrowRecordBatch -> ArrowTable
    break

await raw_sub.unsubscribe()

Key behaviors:

• output accepts exactly record_batch, backend, dict, or tick (case-insensitive); an explicit selector overrides both raw and tick_mode
• raw=True or output="record_batch" yields raw xbbg ArrowRecordBatch values for max-performance consumers
• tick_mode=True, output="dict", or output="tick" returns native dict ticks and implies raw subscription mode
• output="backend" returns the configured backend output, the same as default iteration without raw=True
• all_fields=True exposes all top-level scalar Bloomberg subscription fields; unrequested arrays/complex fields are omitted, while explicitly requested unsupported shapes fail rather than being truncated
• filtered mode keeps requested fields plus MKTDATA_EVENT_TYPE and MKTDATA_EVENT_SUBTYPE
• conflate=True requests Bloomberg-conflated quote updates on //blp/mktdata; trades are still delivered as received
• sub.add(...), sub.remove(...), sub.status, sub.events, sub.failed_tickers, and sub.stats expose runtime control and diagnostics
• use async with on an acquired subscription or try/finally with await sub.unsubscribe() for deterministic cleanup; unsubscribe(drain=True) returns a list in the same dict/raw/backend representation as iteration (an empty drain is []). An unread stream failure is raised after cleanup, never hidden by a successful partial drain.