BLS

You run a standalone MCP server that serves realistic mock BLS data to multiple LLM clients over local stdio or remote SSE connections. It provides a modular set of tools to fetch, list, and visualize BLS data and is designed to work smoothly with both local and remote client setups.

How to use

You interact with the server through MCP clients. Start the server using a local stdio transport for direct, low-latency access or enable SSE transport for remote access via tunneling tools. Once running, you can request BLS data, list available series, inspect metadata for a series, or plot data for visualization.

Typical usage patterns include starting the server in one terminal, then querying through your MCP client to fetch specific series like CPI data, listing available series, or requesting a ready-to-plot data structure for client-side visualization. The server uses mock BLS data that mirrors the actual API structure, enabling rapid development and testing with realistic results.

How to install

Prerequisites: ensure you have Python installed and a working network environment. You will also need a method to run the server either locally or via a remote transport if you plan to test remote connections.

# Prerequisites
python3 --version
pip3 --version

# Install UV (recommended for speed; follow the installation steps in UV docs if needed)
# (If you prefer traditional setup, skip this step)
# uv installation script is external to this guide

# Clone or navigate to the project directory
cd bls_mcp

# Install dependencies using UV (recommended)
# This step creates a virtual environment automatically
uv sync

# Or install dependencies using traditional Python method
# python -m venv venv
# source venv/bin/activate
# pip install -e .

Configuration and running notes

To run the server locally, you have two common options. Choose the method you prefer and run the corresponding command.

Option A: Start with UV (recommended for speed)

./scripts/uv_start_server.sh

Option B: Start with traditional Python

python scripts/start_server.py

Testing the server

Install the MCP inspector tool to validate and interact with the running server from your development environment.

npm install -g @modelcontextprotocol/inspector
mcp-inspector python scripts/start_server.py

Available tools

get_series

Fetch BLS data series by ID with optional start and end year filters.

list_series

List available BLS series with optional category and limit filters.

get_series_info

Retrieve detailed metadata for a specified BLS series.

plot_series

Prepare CPI All Items data for client-side plotting, returning time-series data and plotting instructions.