Bloomberg MCP

A Model Context Protocol server that gives AI assistants direct access to Bloomberg Terminal data.

---

Bloomberg MCP bridges the Bloomberg Terminal with AI assistants via the Model Context Protocol. It exposes 18 tools covering reference data, bulk data, historical analysis, technical analysis, estimates, ownership, supply chain, screening, BQL queries, and calendars — all accessible through natural language.

Enhanced fork of tallinn102/bloomberg-mcp — v1.1 adds 6 new tools, modular architecture, caching layer, and 10 analytical FieldSets.

You: "What are the top holders and supply chain for CEG US Equity?"

Claude: runs bloomberg_get_bulk_data with TOP_20_HOLDERS_PUBLIC_FILINGS
        runs bloomberg_get_supply_chain with suppliers + customers
        → Returns structured holder list + supplier/customer network

Architecture

graph TB
    subgraph Clients
        CC[Claude Code]
        WC[Web Client]
        CA[Custom App]
    end

    subgraph "Bloomberg MCP Server"
        direction TB
        MCP["FastMCP Server<br/><i>18 tools exposed</i>"]

        subgraph Handlers["Handler Layer"]
            direction LR
            REF[Reference & Historical]
            BULK[Bulk Data & Estimates]
            TA[Technical Analysis]
            SCREEN[Screening & BQL]
            OWN[Ownership & Supply Chain]
            CAL[Calendars]
        end

        subgraph Core["Core Layer"]
            direction LR
            SESSION["BloombergSession<br/><i>Singleton + Cache</i>"]
            REQ[Request Builder]
            RESP[Response Parser]
        end
    end

    BBG["Bloomberg Terminal<br/><i>blpapi on port 8194</i>"]

    CC -- stdio --> MCP
    WC -- HTTP/SSE --> MCP
    CA -- HTTP/SSE --> MCP
    MCP --> Handlers
    Handlers --> Core
    SESSION <--> BBG
    REQ --> SESSION
    SESSION --> RESP

    style MCP fill:#1a73e8,stroke:#1557b0,color:#fff
    style BBG fill:#ff6f00,stroke:#e65100,color:#fff
    style SESSION fill:#2e7d32,stroke:#1b5e20,color:#fff

Tools Overview (18 tools)

graph LR
    subgraph "Market Data (4)"
        T1["bloomberg_get_reference_data<br/><i>BDP snapshots</i>"]
        T2["bloomberg_get_historical_data<br/><i>BDH time series</i>"]
        T3["bloomberg_get_intraday_bars<br/><i>OHLCV candles</i>"]
        T4["bloomberg_get_intraday_ticks<br/><i>Raw ticks</i>"]
    end

    subgraph "Bulk Data & Analysis (4)"
        T5["bloomberg_get_bulk_data<br/><i>BDS tables</i>"]
        T6["bloomberg_get_estimates_detail<br/><i>Multi-period consensus</i>"]
        T7["bloomberg_get_ownership<br/><i>Holder analysis</i>"]
        T8["bloomberg_get_supply_chain<br/><i>SPLC network</i>"]
    end

    subgraph "Technical & BQL (2)"
        T9["bloomberg_get_technical_analysis<br/><i>RSI, MACD, Bollinger...</i>"]
        T10["bloomberg_run_bql<br/><i>Query language</i>"]
    end

    subgraph "Discovery (3)"
        T11["bloomberg_search_securities<br/><i>Find by name/ticker</i>"]
        T12["bloomberg_search_fields<br/><i>Field mnemonics</i>"]
        T13["bloomberg_get_field_info<br/><i>Field metadata</i>"]
    end

    subgraph "Screening (3)"
        T14["bloomberg_run_screen<br/><i>Saved EQS screens</i>"]
        T15["bloomberg_get_universe<br/><i>Index constituents</i>"]
        T16["bloomberg_dynamic_screen<br/><i>Custom filter + rank</i>"]
    end

    subgraph "Calendars (2)"
        T17["bloomberg_get_economic_calendar<br/><i>Fed, BoJ, ECB...</i>"]
        T18["bloomberg_get_earnings_calendar<br/><i>Earnings dates</i>"]
    end

    style T5 fill:#1a73e8,stroke:#1557b0,color:#fff
    style T6 fill:#1a73e8,stroke:#1557b0,color:#fff
    style T7 fill:#1a73e8,stroke:#1557b0,color:#fff
    style T8 fill:#1a73e8,stroke:#1557b0,color:#fff
    style T9 fill:#7b1fa2,stroke:#6a1b9a,color:#fff
    style T10 fill:#7b1fa2,stroke:#6a1b9a,color:#fff

What's New (vs upstream)

• Modular architecture — server.py refactored from 1,798 lines to ~89 lines. Handlers, models, formatters, and utils cleanly separated.
• 9 new tools — BDS bulk data, multi-period estimates, technical analysis (//blp/tasvc), ownership analysis, supply chain (SPLC), BQL queries (//blp/bqlsvc), and more.
• Cache layer — TTL-based in-memory cache with data-type-aware expiration (30s for prices, 24h for static data).
• 10 new FieldSets — Pre-defined field collections for estimates, profitability, cash flow, balance sheet, ownership, governance, risk, valuation, earnings surprise, and growth.
• Full Bloomberg API surface — Covers //blp/refdata, //blp/instruments, //blp/apiflds, //blp/tasvc, //blp/bqlsvc.

Data Flow

sequenceDiagram
    participant Client as AI Assistant
    participant MCP as MCP Server
    participant Cache as Cache Layer
    participant Val as Pydantic Validation
    participant Expand as Field Expander
    participant Session as BloombergSession
    participant BBG as Bloomberg Terminal

    Client->>MCP: Tool call (JSON)
    MCP->>Val: Validate input model
    Val-->>MCP: Validated params

    alt FieldSet shortcuts used
        MCP->>Expand: Expand FieldSet shortcuts
        Expand-->>MCP: Resolved field list
    end

    MCP->>Cache: Check cache
    alt Cache hit
        Cache-->>MCP: Cached result
    else Cache miss
        MCP->>Session: Build & send request
        Session->>BBG: blpapi Request
        BBG-->>Session: blpapi Response
        Session-->>MCP: Parsed dataclasses
        MCP->>Cache: Store with TTL
    end

    alt Markdown format
        MCP-->>Client: Formatted table
    else JSON format
        MCP-->>Client: Structured JSON
    end

Bloomberg Services

graph LR
    subgraph "Bloomberg Terminal (localhost:8194)"
        R["//blp/refdata<br/><i>BDP, BDH, BDS, BEQS</i>"]
        I["//blp/instruments<br/><i>Security lookup</i>"]
        F["//blp/apiflds<br/><i>Field discovery</i>"]
        T["//blp/tasvc<br/><i>Technical analysis</i>"]
        B["//blp/bqlsvc<br/><i>Query language</i>"]
    end

    R --- T1[Reference Data]
    R --- T2[Historical Data]
    R --- T3[Intraday Bars/Ticks]
    R --- T4[Bulk Data]
    R --- T5[Estimates]
    R --- T6[Screening]
    I --- T7[Security Search]
    F --- T8[Field Search]
    T --- T9[RSI / MACD / Bollinger]
    B --- T10[Dynamic Queries]

    style R fill:#ff6f00,stroke:#e65100,color:#fff
    style T fill:#7b1fa2,stroke:#6a1b9a,color:#fff
    style B fill:#1a73e8,stroke:#1557b0,color:#fff

Tool Reference

Market Data

Tool	Description	Key Parameters
bloomberg_get_reference_data	Current field values (BDP) for any security	securities, fields, overrides
bloomberg_get_historical_data	Time series (BDH) with configurable periodicity	securities, fields, start_date, end_date, periodicity
bloomberg_get_intraday_bars	OHLCV candles (1/5/15/30/60 min)	security, start_datetime, end_datetime, interval
bloomberg_get_intraday_ticks	Raw tick-level trade/quote data	security, start_datetime, end_datetime, event_types

Bulk Data & Analysis — NEW

Tool	Description	Key Parameters
bloomberg_get_bulk_data	Bulk reference data (BDS) — holders, dividends, supply chain, index members	security, field, overrides, max_rows
bloomberg_get_estimates_detail	Multi-period consensus estimates with revision momentum	securities, periods, metrics
bloomberg_get_ownership	Comprehensive ownership analysis (holders + insider + institutional)	security, include_holders, include_changes
bloomberg_get_supply_chain	Bloomberg SPLC supply chain data (suppliers, customers, competitors)	security, include_suppliers, include_customers

Technical Analysis & BQL — NEW

Tool	Description	Key Parameters
bloomberg_get_technical_analysis	TA indicators via //blp/tasvc (RSI, MACD, Bollinger, SMA, EMA, DMI, Stochastic)	security, indicators, start_date, end_date
bloomberg_run_bql	Execute Bloomberg Query Language queries	query

Discovery

Tool	Description	Key Parameters
bloomberg_search_securities	Find securities by name or partial ticker	query, yellow_key, max_results
bloomberg_search_fields	Discover Bloomberg field mnemonics	query, field_type
bloomberg_get_field_info	Detailed field metadata and documentation	field_ids

Screening

Tool	Description	Key Parameters
bloomberg_run_screen	Execute saved Bloomberg EQS screens	screen_name, screen_type
bloomberg_get_universe	Index/screen constituents with optional fields	source, include_fields
bloomberg_dynamic_screen	Custom filtering, ranking, and field selection	universe, fields, filters, rank_by, top_n

Calendars

Tool	Description	Key Parameters
bloomberg_get_economic_calendar	Upcoming macro releases by region/importance	mode, regions, importance
bloomberg_get_earnings_calendar	Earnings announcements by universe/timing	mode, universe, days_ahead

All tools support response_format: "markdown" (default) or "json".

FieldSet Shortcuts

Instead of remembering Bloomberg field mnemonics, use shorthand names that expand to multiple fields.

Core FieldSets

FieldSet	Fields	Description
PRICE	5	PX_LAST, PX_OPEN, PX_HIGH, PX_LOW, CHG_PCT_1D
MOMENTUM	4	CHG_PCT_1D, CHG_PCT_5D, CHG_PCT_1M, CHG_PCT_YTD
MOMENTUM_EXTENDED	7	+ CHG_PCT_3M, CHG_PCT_6M, CHG_PCT_1YR
RVOL	3+1	VOLUME, VOLUME_AVG_20D, TURNOVER + computed rvol
TECHNICAL	4	RSI_14D, VOLATILITY_30D, VOLATILITY_90D, BETA_RAW_OVERRIDABLE
VALUATION	5	PE_RATIO, PX_TO_BOOK_RATIO, EV_TO_EBITDA, DIVIDEND_YIELD, CUR_MKT_CAP
ANALYST	3	EQY_REC_CONS, BEST_TARGET_PRICE, BEST_EPS
SECTOR	2	GICS_SECTOR_NAME, GICS_INDUSTRY_NAME
SCREENING_FULL	30+	All of the above combined

Analytical FieldSets — NEW

FieldSet	Fields	Key Bloomberg Mnemonics
ESTIMATES_CONSENSUS	10	BEST_EPS, BEST_SALES, BEST_EPS_4WK_CHG, BEST_TARGET_PRICE
PROFITABILITY	7	GROSS_MARGIN, ROE, ROA, ROIC, OPER_MARGIN
CASH_FLOW	6	FCF_YIELD, CF_FROM_OPS, NET_INCOME, EBITDA
BALANCE_SHEET	6	D/E, INTEREST_COV, CUR_RATIO, NET_DEBT
OWNERSHIP	5	INSIDER%, INST%, SHORT_INT_RATIO
GOVERNANCE	4	ESG scores (overall, E, S, G)
RISK	6	BETA, VOL 10/30/90/260D, MKT_CAP
VALUATION_EXTENDED	9	PE, P/B, P/S, EV/EBITDA, P/FCF, DVD_YLD
EARNINGS_SURPRISE	6	EPS/sales actual vs estimate + surprise
GROWTH	4	Sales/EPS/EBITDA growth, LT growth est

Dynamic Screening

The most powerful tool. Build custom screens with pre-validated field sets, filters, and ranking — no need to know Bloomberg field mnemonics.

flowchart LR
    A["Universe<br/><i>index, screen,<br/>or ticker list</i>"] --> B["Field Expansion<br/><i>FieldSet shortcuts<br/>→ Bloomberg fields</i>"]
    B --> C["Bloomberg API<br/><i>ReferenceDataRequest</i>"]
    C --> D["Filter<br/><i>gt, lt, between,<br/>in, eq, ...</i>"]
    D --> E["Rank & Slice<br/><i>rank_by + top_n</i>"]
    E --> F["Response<br/><i>Markdown table<br/>or JSON</i>"]

    style A fill:#e8f5e9,stroke:#2e7d32
    style C fill:#fff3e0,stroke:#ff6f00
    style F fill:#e3f2fd,stroke:#1a73e8

Filter Operators

Operator	Description	Example
gt / gte	Greater than (or equal)	{"field": "rvol", "op": "gt", "value": 1.5}
lt / lte	Less than (or equal)	{"field": "RSI_14D", "op": "lt", "value": 30}
eq / neq	Equals / not equals	{"field": "GICS_SECTOR_NAME", "op": "eq", "value": "Technology"}
between	Range (inclusive)	{"field": "PE_RATIO", "op": "between", "value": [10, 25]}
in	Value in list	{"field": "GICS_SECTOR_NAME", "op": "in", "value": ["Tech", "Health Care"]}

Example: Find Oversold High-Volume Stocks

{
  "universe": "index:SPX Index",
  "fields": ["PRICE", "RVOL", "TECHNICAL", "SECTOR"],
  "filters": [
    {"field": "RSI_14D", "op": "lt", "value": 30},
    {"field": "rvol", "op": "gt", "value": 2.0}
  ],
  "rank_by": "rvol",
  "rank_descending": true,
  "top_n": 20
}

Common BDS (Bulk Data) Fields

Field	Returns
TOP_20_HOLDERS_PUBLIC_FILINGS	Top 20 shareholders with positions and dates
DVD_HIST_ALL	Complete dividend history
SUPPLY_CHAIN_SUPPLIERS	Supplier list with revenue exposure
SUPPLY_CHAIN_CUSTOMERS	Customer list with revenue exposure
SUPPLY_CHAIN_COMPETITORS	Competitor list
INDX_MEMBERS	Index constituents
ANALYST_RECOMMENDATIONS	Analyst ratings detail
EARN_ANN_DT_TIME_HIST_WITH_EPS	Historical earnings with actual EPS
BOARD_OF_DIRECTORS	Board members

Cache Layer

The built-in cache reduces Bloomberg API load with data-type-aware TTLs:

Data Type	TTL	Rationale
Static reference (name, sector)	24 hours	Rarely changes
Financial statements	7 days	Quarterly updates
Estimates / consensus	4 hours	Updates throughout day
Price / volume	30 seconds	Near real-time
Historical (EOD)	12 hours	End-of-day data stable
Bulk data (holders, supply chain)	24 hours	Daily updates

Project Structure

graph TB
    subgraph "src/bloomberg_mcp/"
        SERVER["server.py<br/><i>~89 lines, thin entry point</i>"]

        subgraph models["models/"]
            INPUTS["inputs.py<br/><i>22 Pydantic models</i>"]
            ENUMS["enums.py<br/><i>ResponseFormat, modes</i>"]
        end

        subgraph handlers["handlers/"]
            direction TB
            H_REF["reference.py"]
            H_HIST["historical.py"]
            H_INTRA["intraday.py"]
            H_SEARCH["search.py"]
            H_SCREEN["screening.py"]
            H_CAL["calendars.py"]
            H_BULK["bulk.py ★"]
            H_EST["estimates.py ★"]
            H_TECH["technical.py ★"]
            H_OWN["ownership.py ★"]
            H_SC["supply_chain.py ★"]
            H_BQL["bql.py ★"]
        end

        FMTR["formatters.py"]
        UTILS["utils.py"]

        subgraph core["core/"]
            SESSION["session.py<br/><i>Singleton</i>"]
            CACHE["cache.py ★<br/><i>TTL cache</i>"]
            REQ["requests.py"]
            RESP["responses.py"]
        end

        subgraph tools["tools/"]
            direction TB
            T_REF["reference.py"]
            T_HIST["historical.py"]
            T_SEARCH["search.py"]

            subgraph ds["dynamic_screening/"]
                MODELS_DS["models.py<br/><i>19+ FieldSets</i>"]
                SCREEN_DS["screen.py"]
                FILTERS["filters.py"]
            end

            subgraph mn["morning_note/"]
                MN_CFG["config.py"]
                MN_US["us_session.py"]
                MN_STORE["storage.py"]
            end
        end
    end

    SERVER --> handlers
    SERVER --> models
    handlers --> core
    handlers --> FMTR
    handlers --> UTILS

    style SERVER fill:#1a73e8,stroke:#1557b0,color:#fff
    style SESSION fill:#2e7d32,stroke:#1b5e20,color:#fff
    style CACHE fill:#2e7d32,stroke:#1b5e20,color:#fff
    style H_BULK fill:#e65100,stroke:#bf360c,color:#fff
    style H_EST fill:#e65100,stroke:#bf360c,color:#fff
    style H_TECH fill:#e65100,stroke:#bf360c,color:#fff
    style H_OWN fill:#e65100,stroke:#bf360c,color:#fff
    style H_SC fill:#e65100,stroke:#bf360c,color:#fff
    style H_BQL fill:#e65100,stroke:#bf360c,color:#fff

<small>★ = New in v1.1</small>

Installation

Prerequisites

• Python 3.10+
• Bloomberg Terminal running and logged in — connects via localhost:8194

Setup

# 1. Install Bloomberg Python SDK
pip install blpapi

# 2. Install bloomberg-mcp
git clone https://github.com/QmQsun/Bloomberg-MCP.git
cd Bloomberg-MCP
pip install .            # standard install
# or: pip install -e .   # editable mode (for development)

Note: blpapi 3.19.0+ ships pre-built wheels — pip install blpapi works directly on Windows, macOS, and Linux without additional setup.

If pip install blpapi fails (older platforms or Python versions), install via the C++ SDK:

# Set Bloomberg C++ SDK path
export BLPAPI_ROOT=/path/to/blpapi_cpp_3.x.x.x   # Linux/macOS
set BLPAPI_ROOT=C:\blp\blpapi_cpp_3.x.x.x         # Windows
pip install blpapi

Configure Claude Code

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "bloomberg-mcp": {
      "command": "python",
      "args": ["-m", "bloomberg_mcp.server"],
      "cwd": "/path/to/bloomberg-mcp",
      "env": {
        "BLOOMBERG_HOST": "localhost",
        "BLOOMBERG_PORT": "8194"
      }
    }
  }
}

Configure GPT Codex

Add to your codex config.toml

[mcp_servers.bloomberg-mcp]
command = "python"
args = ["-m", "bloomberg_mcp.server"]
cwd = "/path/to/bloomberg-mcp"

[mcp_servers.bloomberg-mcp.env]
BLOOMBERG_HOST = "localhost"
BLOOMBERG_PORT = "8194"

if it cannot load to codex, check your cwd path

Quick Start

As a Python Library

from bloomberg_mcp.tools import get_reference_data, get_historical_data

# Current prices and fundamentals
data = get_reference_data(
    securities=["AAPL US Equity", "700 HK Equity", "2899 HK Equity"],
    fields=["PX_LAST", "PE_RATIO", "DIVIDEND_YIELD"]
)
for sec in data:
    print(f"{sec.security}: {sec.fields.get('PX_LAST')}")

# Multi-period estimates with overrides
data = get_reference_data(
    securities=["CEG US Equity"],
    fields=["BEST_EPS", "BEST_EPS_4WK_CHG", "BEST_TARGET_PRICE"],
    overrides={"BEST_FPERIOD_OVERRIDE": "1FY"}
)

# Historical time series
hist = get_historical_data(
    securities=["SPY US Equity"],
    fields=["PX_LAST", "VOLUME"],
    start_date="20240101",
    end_date="20241231",
    periodicity="DAILY"
)

As an MCP Server

# stdio (default — for Claude Code)
python -m bloomberg_mcp.server

# HTTP transport (for web clients)
python -m bloomberg_mcp.server --http --port=8080

# SSE transport (for streaming clients)
python -m bloomberg_mcp.server --sse --port=8080

Docker Deployment

graph LR
    subgraph Docker
        MCP["bloomberg-mcp<br/><i>:8080</i>"]
    end

    subgraph Host
        BBG["Bloomberg Terminal<br/><i>:8194</i>"]
    end

    Client["AI Client"] -- "HTTP/SSE" --> MCP
    MCP -- "host.docker.internal:8194" --> BBG

    style MCP fill:#1a73e8,stroke:#1557b0,color:#fff
    style BBG fill:#ff6f00,stroke:#e65100,color:#fff

docker-compose up -d
docker-compose logs -f bloomberg-mcp

Security Identifier Formats

AAPL US Equity       # US stock
VOD LN Equity        # UK stock (London)
7203 JP Equity       # Japan stock (numeric)
700 HK Equity        # Hong Kong stock
1133 HK Equity       # Hong Kong stock (numeric)
601012 CH Equity     # A-share (Shanghai)
002594 CH Equity     # A-share (Shenzhen)
300750 CH Equity     # A-share (ChiNext)
SPX Index            # Index
HSI Index            # Hang Seng Index
VIX Index            # Volatility index
EUR Curncy           # Currency
CL1 Comdty           # Commodity future
SPY US Equity        # ETF

Contributing

Contributions welcome! Please open an issue or submit a pull request.

pip install -e ".[dev]"
pytest                    # Unit tests (no Bloomberg needed)
pytest tests/integration/ # Integration tests (needs Terminal)
black src/ tests/
ruff check src/ tests/

Contributors

	Contributor	Role
1	QmQsun	Architecture refactor, 6 new tools, caching layer, FieldSets, code review
2	srarmy2005	Bug discovery (__main__ double-import fix)
3	Claude (Anthropic)	Implementation assistance, code generation, QA
4	tallinn102	Original project foundation

License

MIT — see LICENSE for details.