# bls-labor-mcp-server [Health: Active]

**Category:** 🧮 Data Science Tools  
**Repository:** https://github.com/cyanheads/bls-labor-mcp-server  
**GitHub Stars:** 1  
**npm Downloads (last month):** 1501  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/bls-labor-mcp-server

## Description
Fetch US Bureau of Labor Statistics data — CPI, unemployment, wages, JOLTS, and more via MCP.

## Tools
Capabilities this server exposes over MCP:

- **bls_list_surveys** — List BLS survey programs (CPI, CPS, CES, JOLTS, PPI, OEWS, …) with codes, descriptions, and calculation-support flags.
- **bls_search_series** — Search the BLS series catalog by natural language, survey, area, or keywords to resolve cryptic SeriesIDs.
- **bls_get_series** — Fetch time-series data for 1–50 BLS series by SeriesID, with optional year range and period-over-period calculations.
- **bls_get_latest** — Return the single most recent observation for one or more BLS series.
- **bls_dataframe_describe** — List canvas dataframes registered by `bls_get_series` or `bls_dataframe_query` — provenance, TTL, row count, column schema. Available when `CANVAS_PROVIDER_TYPE=duckdb`.
- **bls_dataframe_query** — Run a SELECT against canvas dataframes registered by `bls_get_series` or an earlier `register_as`. Supports JOINs, aggregates, window functions, CTEs. Available when `CANVAS_PROVIDER_TYPE=duckdb`.
- **bls_dataframe_drop** — Drop a canvas dataframe by name. Available when `CANVAS_PROVIDER_TYPE=duckdb` and `BLS_DATAFRAME_DROP_ENABLED=true`; TTL handles cleanup by default.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `bunx` (confidence: high):

```json
"mcpServers": {
  "bls-labor-mcp-server": {
    "command": "bunx",
    "args": ["@cyanheads/bls-labor-mcp-server@latest"],
    "env": {
      "BLS_API_KEY": "",
      "CANVAS_PROVIDER_TYPE": "",
      "BLS_DATAFRAME_DROP_ENABLED": "",
      "BLS_CATALOG_INCLUDE_OES": ""
    }
  }
}
```

**Requires environment variables:** `BLS_API_KEY`, `CANVAS_PROVIDER_TYPE`, `BLS_DATAFRAME_DROP_ENABLED`, `BLS_CATALOG_INCLUDE_OES` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What bls-labor-mcp-server does

The bls-labor-mcp-server MCP server exposes U.S. Bureau of Labor Statistics data to MCP clients. It covers survey programs such as CPI, CPS, CES, JOLTS, PPI, and OEWS. Agents can inspect available surveys, search the BLS catalog for series, retrieve historical observations, or request the newest observation for one or more series.

Series discovery uses an offline LABSTAT index, so searching for a description, survey, area, keyword, or existing SeriesID does not consume BLS API quota. The search response includes decoded identifiers, titles, frequency, pagination information, and catalog metadata. OE/OEWS catalog indexing is optional, while unindexed series can still be fetched when their SeriesIDs are known.

## How it works

The server supports stdio and Streamable HTTP transports, including a hosted Streamable HTTP endpoint documented by the project. Its BLS client uses API v2 for data retrieval. A `bls_get_series` request can contain 1–50 SeriesIDs, an optional year window of up to 20 years, calculation options, and annual-average handling. BLS-supported calculations are applied server-side; support varies by survey.

`bls_get_latest` retrieves one current observation per requested series. It reports successful and failed items separately, which lets an agent continue when only some identifiers are invalid or unavailable. Missing BLS values remain distinguishable through the returned availability fields.

With DuckDB DataCanvas enabled, larger results can be registered as dataframes. Agents can inspect their schemas and provenance, then run read-only SELECT statements using joins, aggregates, window functions, and common table expressions. Query results may be registered again for chained analysis, and dataframe entries have a time-to-live.

## Setup and configuration

The package can run as a local process or Streamable HTTP service. The repository also documents Docker and npm distribution, plus installation links for Claude Desktop, Cursor, and VS Code. A BLS API key is supplied through `BLS_API_KEY` in the documented client configuration.

Set `CANVAS_PROVIDER_TYPE=duckdb` to enable dataframe inspection and SQL tools. Set `BLS_DATAFRAME_DROP_ENABLED=true` only if explicit dataframe deletion should be available; otherwise, TTL-based cleanup remains the default. `BLS_CATALOG_INCLUDE_OES` controls whether the large OE/OEWS wage catalog is included in the offline search index.

## Tools and capabilities

The default BLS workflow uses four tools:

- `bls_list_surveys` lists survey codes, descriptions, and calculation-support flags.
- `bls_search_series` resolves natural-language descriptions and filters into SeriesIDs.
- `bls_get_series` retrieves batched historical data and optional calculations.
- `bls_get_latest` returns the newest observation for up to 50 SeriesIDs.

DuckDB adds `bls_dataframe_describe` and `bls_dataframe_query`. `bls_dataframe_drop` is an additional opt-in tool. SQL queries are limited to SELECT statements, cannot read external files or system catalogs, and return at most 10,000 rows, with a default limit of 1,000.

## Limitations and notes

The bls-labor-mcp-server MCP server depends on BLS series identifiers and the BLS API's availability and quota rules. A latest-value request makes one API query per SeriesID, so batched historical retrieval is more efficient for multiple series. `bls_get_series` accepts at most 50 series per call and a year range of up to 20 years.

Calculation behavior is survey-dependent: the documented CPI and PPI support includes percent changes, while other calculations may not be available. Large responses require DuckDB DataCanvas; without it, the server asks for a narrower window when results cannot be returned directly. Dataframe entries expire, and dataframe column types outside the supported canvas set may be represented as `VARCHAR`.

_Full upstream README: https://allmcps.com/mcp/bls-labor-mcp-server/readme_