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

★ = New in v1.1

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

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.

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
examples		examples
src/bloomberg_mcp		src/bloomberg_mcp
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
run_server.bat		run_server.bat
run_server.ps1		run_server.ps1

Folders and files

Latest commit

History

Repository files navigation

Bloomberg MCP

Architecture

Tools Overview (18 tools)

What's New (vs upstream)

Data Flow

Bloomberg Services

Tool Reference

Market Data

Bulk Data & Analysis — NEW

Technical Analysis & BQL — NEW

Discovery

Screening

Calendars

FieldSet Shortcuts

Core FieldSets

Analytical FieldSets — NEW

Dynamic Screening

Filter Operators

Example: Find Oversold High-Volume Stocks

Common BDS (Bulk Data) Fields

Cache Layer

Project Structure

Installation

Prerequisites

Setup

Configure Claude Code

Quick Start

As a Python Library

As an MCP Server

Docker Deployment

Security Identifier Formats

Contributing

Contributors

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages