BLS MCP

An MCP (Model Context Protocol) server that wraps the Bureau of Labor Statistics Public Data API v2, letting Claude query U.S. labor statistics — employment, unemployment, wages, CPI, and more — directly from a conversation.

Disclaimer: This project is an independent, unofficial tool and is not affiliated with, endorsed by, or associated with the U.S. Bureau of Labor Statistics, the U.S. Department of Labor, or any government agency. All data is fetched in real time from the publicly available api.bls.gov API. The accuracy, completeness, and timeliness of the data are the sole responsibility of that API. This tool is provided for informational and research purposes only. Nothing returned by this server constitutes legal, financial, economic, or policy advice. Use responsibly and in accordance with applicable laws.

API status: The BLS Public Data API is at v0.0.2-beta and subject to change without notice. Tool behaviour may change as the upstream API evolves.

Available Tools

Tool	Endpoint	Description
get_single_series	GET /timeseries/data/{id}	Retrieve data for a single time series for the past three years
get_latest_series	GET /timeseries/data/{id}?latest=true	Retrieve the most recent data point for a series
get_multiple_series	POST /timeseries/data/	Retrieve data for one or more series with optional parameters
get_popular_series	GET /timeseries/popular	List the 25 most popular BLS series, optionally filtered by survey
get_all_surveys	GET /surveys	List all BLS surveys with abbreviations and names
get_survey	GET /surveys/{abbr}	Retrieve metadata for a single BLS survey

Tool Parameters

get_single_series / get_latest_series

Parameter	Type	Description
series_id	string	BLS series ID (uppercase, digits, _, -, #)

get_multiple_series

Parameter	Type	Required	Description
series_ids	string[]	Yes	Array of BLS series IDs (1–50)
start_year	string	No	Start year in YYYY format
end_year	string	No	End year in YYYY format
catalog	boolean	No	Include catalog data (requires API key)
calculations	boolean	No	Include net/percent change calculations (requires API key)
annual_average	boolean	No	Include annual averages (requires API key)
aspects	boolean	No	Include aspect data (requires API key)

get_popular_series

Parameter	Type	Required	Description
survey	string	No	2-letter survey abbreviation (e.g. LA, CU, CE)

get_survey

Parameter	Type	Required	Description
survey_abbreviation	string	Yes	2-letter survey abbreviation (e.g. TU, CU, LA)

get_all_surveys — no parameters.

Series ID Format

BLS series IDs may contain uppercase letters, digits, underscores (_), dashes (-), and hashes (#). Lowercase letters and other special characters are not accepted. Examples:

• LAUCN040010000000005 — Local Area Unemployment
• CUUR0000SA0 — Consumer Price Index
• CES0000000001 — Current Employment Statistics
• OEUN000000056--5747213213 — Occupational Employment

Use get_popular_series or get_all_surveys to discover valid series IDs and survey abbreviations.

Registered vs. Unregistered Access

The BLS API works without an API key, but with reduced limits:

	Unregistered	Registered
Daily query limit	25	500
Series per query	25	50
Year range	10 years	20 years
Optional parameters	No	catalog, calculations, annual averages, aspects

Register for a free API key at https://data.bls.gov/registrationEngine/ and pass it via the BLS_API_KEY environment variable.

Prerequisites

• Node.js 18 or later
• npm 9 or later
• Claude Desktop (or any MCP-compatible client)

Installation

git clone https://github.com/larasrinath/bls_mcp.git
cd bls_mcp
npm install
npm run build

The compiled server lands in ./dist/index.js.

Claude Desktop Configuration

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

Add the following block (adjust the path to match your machine):

{
  "mcpServers": {
    "bls": {
      "command": "node",
      "args": ["/absolute/path/to/bls_mcp/dist/index.js"],
      "env": {
        "BLS_API_KEY": "your-registration-key-here"
      }
    }
  }
}

The env block is optional — omit it to use the API without a key (lower rate limits apply).

macOS/Linux example:

"args": ["/Users/yourname/Projects/bls_mcp/dist/index.js"]

Windows example:

"args": ["C:\\Users\\yourname\\Projects\\bls_mcp\\dist\\index.js"]

Restart Claude Desktop after saving. The six BLS tools will appear in the tool picker.

Bundled Skill

This repo includes a Claude skill at skills/bls-query/ that teaches Claude how to map natural language queries (e.g. "What's the current CPI?") to the correct BLS series IDs and tools — without guessing.

The skill includes a series catalog covering CPI, unemployment, employment, JOLTS, PPI, wages, productivity, and more (~100 common series IDs).

To install for Claude Code: Copy the skills/bls-query folder into ~/.claude/skills/.

To install for Claude.ai: Upload the skills/bls-query folder via Settings > Capabilities > Skills.

Example Prompts

• What is the current unemployment rate? (use get_popular_series to find the series, then get_latest_series)
• Show me CPI data for the last 3 years using series CUUR0000SA0.
• Compare employment data for series CES0000000001 and CES3000000001 from 2020 to 2024.
• What BLS surveys are available?
• Tell me about the American Time Use survey.
• What are the most popular Local Area Unemployment series?

Development

# Run directly without building (uses tsx, included in devDependencies)
npm run dev

# Rebuild after changes
npm run build

Project Structure

bls_mcp/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── client.ts         # Typed BLS API client (axios)
│   └── tools/
│       ├── series.ts     # get_single_series, get_latest_series, get_multiple_series
│       └── surveys.ts    # get_popular_series, get_all_surveys, get_survey
├── skills/
│   └── bls-query/
│       ├── SKILL.md      # Query workflow and tool selection guide
│       └── references/
│           └── series-catalog.md  # ~100 common series ID mappings
├── package.json
├── tsconfig.json
├── LICENSE
└── README.md

Rate Limits

The BLS API enforces daily query limits (25 for unregistered, 500 for registered users). If you hit a rate limit, the server surfaces a clear error message rather than crashing silently. Register for a free API key to increase your limits.

License

MIT — see LICENSE.