io.github.cyanheads/bls-labor-mcp-server

Official6 toolsLive

by cyanheads · TypeScript

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

Fetches US Bureau of Labor Statistics data via Model Context Protocol (MCP), covering CPI, unemployment, wages, JOLTS, and more. It exposes tools over STDIO or Streamable HTTP. The repository indicates “4 Tools by default,” with 6 when using DataCanvas and 7 with an opt-in drop.

🛠️ Key Features

MCP server for Bureau of Labor Statistics data
Provides CPI, unemployment, wages, and JOLTS (and additional BLS datasets)
Tool delivery via STDIO or Streamable HTTP
Tool count varies: 4 by default, 6 with DataCanvas, 7 with opt-in drop

🚀 Use Cases

Retrieve time-series labor and economic indicators from BLS
Support unemployment, wage, and inflation-related analysis pipelines
Query labor market metrics such as JOLTS via MCP tools

⚡ Developer Benefits

Standardized MCP interface for BLS data access
Explicit tool surface area (6 tools stated in metadata)
Compatible with developer environments using MCP, including TypeScript-focused stacks

⚠️ Limitations

Tool availability depends on configuration (4 default; 6 with DataCanvas; 7 with opt-in drop)

Topics

blsbureau-of-labor-statisticscpieconomicsmcpmcp-servermodel-context-protocoltime-seriestypescriptunemploymentbunjoltslabor-marketppiwagescyanheads

Captured live from the server via tools/list.

bls_list_surveys

List BLS survey programs with their abbreviation codes, full names, and metadata about calculation support and annual averages. Use to discover which survey covers a topic before calling bls_search_series; bls_search_series covers only the surveys in its offline index, and series in the others are fetched by SeriesID with bls_get_series. Optional category filter narrows results to prices, employment, wages, productivity, injuries, or time_use surveys.

Parameters1

bls_search_series

Search the BLS series catalog by natural language query, survey code, geographic area, or keywords to resolve cryptic SeriesIDs. Returns matching series with decoded components (survey, area, item, seasonal flag, and publication frequency for surveys that publish one series at several frequencies) and plain-language names, ranked by relevance and paged with limit and offset. Use this before bls_get_series when you have a concept but not a SeriesID. Operates offline against an index of the major surveys — no API quota consumed. Survey filter accepts the two-letter code of an indexed survey (CU, AP, CE, LN, LA, PC, WP, JT, EC, PR, MP, CW, CM, CI; OE only when the server sets BLS_CATALOG_INCLUDE_OES=true); series in other surveys are fetched by SeriesID with bls_get_series. Area filter accepts state names, MSA names, or FIPS area codes.

Parameters6

query	string	required	Natural language or keyword query (e.g. "unemployment rate", "CPI food", "nonfarm payrolls"). Also accepts a SeriesID directly for exact lookup.
survey	string	optional	Two-letter LABSTAT survey abbreviation to filter results, case-insensitive (e.g. CU for CPI, CE for CES, LN for CPS, LA for LAUS, JT for JOLTS). Indexed surveys: CU, AP, CE, LN, LA, PC, WP, JT, EC, PR, MP, CW, CM, CI; OE (OEWS) only when the server sets BLS_CATALOG_INCLUDE_OES=true. Omit to search all indexed surveys.
area	string	optional	State name, MSA name, or FIPS area code to narrow results to a geographic area — a case-insensitive substring of the area name, title, or SeriesID. Omit for national series, which then rank first among equal matches.
seasonal_adjustment	boolean	optional	When true, return only seasonally adjusted series. When false, return only not-seasonally-adjusted. Omit to return both.
limit	integer	optional	Maximum number of results to return (1–50, default 10).
offset	integer	optional	Number of ranked results to skip, for paging past the first page (default 0). Pass nextOffset from the previous response to get the next page.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Natural language or keyword query (e.g. \"unemployment rate\", \"CPI food\", \"nonfarm payrolls\"). Also accepts a SeriesID directly for exact lookup."
    },
    "survey": {
      "description": "Two-letter LABSTAT survey abbreviation to filter results, case-insensitive (e.g. CU for CPI, CE for CES, LN for CPS, LA for LAUS, JT for JOLTS). Indexed surveys: CU, AP, CE, LN, LA, PC, WP, JT, EC, PR, MP, CW, CM, CI; OE (OEWS) only when the server sets BLS_CATALOG_INCLUDE_OES=true. Omit to search all indexed surveys.",
      "type": "string"
    },
    "area": {
      "description": "State name, MSA name, or FIPS area code to narrow results to a geographic area — a case-insensitive substring of the area name, title, or SeriesID. Omit for national series, which then rank first among equal matches.",
      "type": "string"
    },
    "seasonal_adjustment": {
      "description": "When true, return only seasonally adjusted series. When false, return only not-seasonally-adjusted. Omit to return both.",
      "type": "boolean"
    },
    "limit": {
      "default": 10,
      "description": "Maximum number of results to return (1–50, default 10).",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "offset": {
      "default": 0,
      "description": "Number of ranked results to skip, for paging past the first page (default 0). Pass nextOffset from the previous response to get the next page.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

bls_get_latest

Return the single most recent observation for one or more BLS series. Use for "what is X right now" questions — the current unemployment rate, the latest CPI reading, etc. Each series consumes one API query against the 500/day limit; for the current value of many series, bls_get_series with a 1-year window is more quota-efficient (one query for up to 50 series). Recommended limit: 10 series; maximum: 50.

Parameters1

series_ids

array

required

One or more BLS SeriesIDs (1–50). Each consumes one daily API query. Use bls_search_series to resolve concepts to SeriesIDs. Recommended: ≤10 series.

Raw schema

{
  "type": "object",
  "properties": {
    "series_ids": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "One or more BLS SeriesIDs (1–50). Each consumes one daily API query. Use bls_search_series to resolve concepts to SeriesIDs. Recommended: ≤10 series."
    }
  },
  "required": [
    "series_ids"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

bls_get_series

Fetch time-series data for 1–50 BLS series by SeriesID in a single API request (one query against the 500/day limit). Supports optional year range (up to 20 years per request) and BLS-computed period-over-period calculations (net change and percent change; a survey returns whichever it supports and silently omits the rest — CPI and PPI return percent change only, the inflation rate). BLS can publish a '-' missing-value sentinel; check observation.available before arithmetic. Set annual_average to add each year's annual-average row, which is that year's mean rather than an additional period. When the total observation count would exceed the inline context budget, results spill to a canvas dataframe and the response includes a dataset.name handle. Call bls_dataframe_describe with that name to inspect the dataframe schema, then use the name in bls_dataframe_query SQL. Use bls_search_series first if you need to resolve a concept to a SeriesID.

Parameters5

series_ids	array	required	One or more BLS SeriesIDs (1–50). The entire batch counts as one API query. Use bls_search_series to resolve concepts to SeriesIDs.
start_year	integer	optional	Start year for the data range (inclusive). The BLS API allows up to 20 years per request and requires both bounds or neither: supplying start_year alone resolves end_year to the current year, capped at start_year + 19 so the window stays inside the 20-year limit. Omit both for the API default (typically 3–20 years depending on survey).
end_year	integer	optional	End year for the data range (inclusive). Supplying it without start_year is rejected before the request — BLS applies no default start year alongside an explicit end year. Pair it with start_year, or omit both for the API default window.
calculations	boolean	optional	When true, request BLS-computed period-over-period calculations. The flag is a single boolean (you cannot select an individual calculation type), but the API returns whichever the survey supports and omits the rest — CPI and PPI return percent change only (the inflation rate), and a survey that supports neither simply returns its observations without calculation fields. Requesting calculations never fails, so it is always safe to set; consult bls_list_surveys (allowsNetChange / allowsPercentChange) only to predict which fields will come back. Monthly-cadence series return each supported change type over 1, 3, 6, and 12-month intervals; other cadences return a subset. A series served from the local observation mirror, when the server runs one, carries no calculation fields; enrichment.calculationsApplied is then false and notice names it.
annual_average	boolean	optional	When true, add each year's annual-average row to the observations. An annual average is the mean of that year's real periods, returned as an extra row named "Annual" with period M13 (monthly series), Q05 (quarterly) or S03 (semiannual) — not an additional month or quarter, so it must be excluded from any sum or average over observations. Defaults to false, which returns real periods only; check available before aggregating. Independent of start_year/end_year. Surveys that publish no annual averages return the same rows either way; enrichment.annualAverageRows reports how many rows were actually added.

Raw schema

{
  "type": "object",
  "properties": {
    "series_ids": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "One or more BLS SeriesIDs (1–50). The entire batch counts as one API query. Use bls_search_series to resolve concepts to SeriesIDs."
    },
    "start_year": {
      "description": "Start year for the data range (inclusive). The BLS API allows up to 20 years per request and requires both bounds or neither: supplying start_year alone resolves end_year to the current year, capped at start_year + 19 so the window stays inside the 20-year limit. Omit both for the API default (typically 3–20 years depending on survey).",
      "type": "integer",
      "minimum": 1900,
      "maximum": 2100
    },
    "end_year": {
      "description": "End year for the data range (inclusive). Supplying it without start_year is rejected before the request — BLS applies no default start year alongside an explicit end year. Pair it with start_year, or omit both for the API default window.",
      "type": "integer",
      "minimum": 1900,
      "maximum": 2100
    },
    "calculations": {
      "description": "When true, request BLS-computed period-over-period calculations. The flag is a single boolean (you cannot select an individual calculation type), but the API returns whichever the survey supports and omits the rest — CPI and PPI return percent change only (the inflation rate), and a survey that supports neither simply returns its observations without calculation fields. Requesting calculations never fails, so it is always safe to set; consult bls_list_surveys (allowsNetChange / allowsPercentChange) only to predict which fields will come back. Monthly-cadence series return each supported change type over 1, 3, 6, and 12-month intervals; other cadences return a subset. A series served from the local observation mirror, when the server runs one, carries no calculation fields; enrichment.calculationsApplied is then false and notice names it.",
      "type": "boolean"
    },
    "annual_average": {
      "default": false,
      "description": "When true, add each year's annual-average row to the observations. An annual average is the mean of that year's real periods, returned as an extra row named \"Annual\" with period M13 (monthly series), Q05 (quarterly) or S03 (semiannual) — not an additional month or quarter, so it must be excluded from any sum or average over observations. Defaults to false, which returns real periods only; check available before aggregating. Independent of start_year/end_year. Surveys that publish no annual averages return the same rows either way; enrichment.annualAverageRows reports how many rows were actually added.",
      "type": "boolean"
    }
  },
  "required": [
    "series_ids"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

bls_dataframe_describe

List canvas dataframes materialized by bls_get_series or by bls_dataframe_query register_as, with provenance (source tool, query parameters), TTL, row count, and column schema. Use before writing SQL to confirm column names and types. Lazy-sweeps expired tables before responding. Requires CANVAS_PROVIDER_TYPE=duckdb.

Parameters1

name

string

optional

Optional dataframe name to describe a single dataframe — a df_XXXXX_XXXXX name from bls_get_series, or a register_as name from bls_dataframe_query. Omit, or leave blank, to list all active dataframes.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "description": "Optional dataframe name to describe a single dataframe — a df_XXXXX_XXXXX name from bls_get_series, or a register_as name from bls_dataframe_query. Omit, or leave blank, to list all active dataframes.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

bls_dataframe_query

Run a single-statement SELECT against the canvas dataframes registered by bls_get_series or by an earlier register_as. Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected. System catalogs (information_schema, pg_catalog, sqlite_master, duckdb_*) are denied at the bridge layer — use bls_dataframe_describe to list available dataframes. Supports JOINs, aggregates, window functions, and CTEs. Optional register_as persists the result as a new dataframe with a fresh TTL for chained analysis. Canvas SQL operations consume zero BLS API quota. Requires CANVAS_PROVIDER_TYPE=duckdb.

Parameters4

sql	string	required	Single-statement SELECT against df_<id> tables on the shared canvas. Reference dataframes by the names returned in bls_get_series responses or listed by bls_dataframe_describe. Standard DuckDB SQL — joins, aggregates, window functions, CTEs all supported. Example: SELECT series_id, year, period, value FROM df_AAAAA_BBBBB WHERE year >= '2020' ORDER BY year DESC.
register_as	string	optional	When set, persist the query result as a new dataframe under this name. Fresh TTL — not inherited from parent tables. Use to chain analyses without re-running source SQL or consuming additional BLS quota.
preview	integer	optional	Inline row preview count. Defaults to row_limit. Set lower (e.g. 50) when chaining via register_as and only a sample is needed immediately.
row_limit	integer	optional	Hard cap on rows materialized in the response (default 1000, max 10000). Full results live on-canvas under register_as when provided.

Raw schema

{
  "type": "object",
  "properties": {
    "sql": {
      "type": "string",
      "minLength": 1,
      "description": "Single-statement SELECT against df_<id> tables on the shared canvas. Reference dataframes by the names returned in bls_get_series responses or listed by bls_dataframe_describe. Standard DuckDB SQL — joins, aggregates, window functions, CTEs all supported. Example: SELECT series_id, year, period, value FROM df_AAAAA_BBBBB WHERE year >= '2020' ORDER BY year DESC."
    },
    "register_as": {
      "description": "When set, persist the query result as a new dataframe under this name. Fresh TTL — not inherited from parent tables. Use to chain analyses without re-running source SQL or consuming additional BLS quota.",
      "type": "string"
    },
    "preview": {
      "description": "Inline row preview count. Defaults to row_limit. Set lower (e.g. 50) when chaining via register_as and only a sample is needed immediately.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000
    },
    "row_limit": {
      "default": 1000,
      "description": "Hard cap on rows materialized in the response (default 1000, max 10000). Full results live on-canvas under register_as when provided.",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    }
  },
  "required": [
    "sql"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md19 KBView on GitHub

@cyanheads/bls-labor-mcp-server

Fetch US Bureau of Labor Statistics data — CPI, unemployment, wages, JOLTS, and more via MCP. STDIO or Streamable HTTP.

4 Tools by default · 6 with DataCanvas · 7 with opt-in drop

MCP SDK TypeScript

Public Hosted Server: https://bls-labor.caseyjhand.com/mcp

Overview

US labor statistics from the Bureau of Labor Statistics public API v2 and LABSTAT flat-file catalog. Resolve opaque SeriesIDs from natural language, fetch historical time-series or the latest observation, and query large multi-series results with SQL through an optional DataCanvas. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Tool	Description
`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.

Capability reference

`bls_list_surveys` _tool

Optional category filters survey programs by subject; returns codes, names, and calculation-support flags (allowsNetChange, allowsPercentChange, hasAnnualAverages).
Backed by the BLS surveys API with monthly caching. Annual-average support is advisory; read bls_get_series's annualAverageRows for the rows actually returned.

`bls_search_series` _tool

Search by text or SeriesID, with optional survey, area (substring of area, title, or SeriesID), and seasonal_adjustment; blank filters are omitted. limit is 1–50 (default 10), with offset pagination; without an area filter, equally matching national series rank first.
Returns decoded SeriesIDs, titles, and frequency. Follow nextOffset while truncated is true; capped: true makes totalCount a lower bound, and paging stops at the FTS candidate pool.
Searches the offline LABSTAT index without using API quota; OE/OEWS is opt-in through BLS_CATALOG_INCLUDE_OES. Unindexed surveys remain fetchable by SeriesID.

`bls_get_series` _tool

Fetch 1–50 SeriesIDs per call, with a start_year/end_year window of up to 20 years, optional calculations, and annual_average. A start alone resolves the end to the current year capped at start + 19; an end alone is rejected. One batch consumes one API query; calculations depend on survey support (CPI/PPI return percent change only).
Returns observations with available, preserves the raw - missing-value sentinel, and keeps valid series in mixed batches. Enrichment reports the applied year window, calculations, and annual-average rows.
Large results spill to dataset.name when CANVAS_PROVIDER_TYPE=duckdb; otherwise canvas_unavailable asks for a narrower window.

`bls_get_latest` _tool

Fetch the latest observation for up to 50 SeriesIDs (recommended ≤10). Each ID consumes one API query; use bls_get_series for a more efficient multi-series batch.
Returns successful results[] beside per-series failed[] entries. latestObservation.available distinguishes a published value from BLS's missing-value sentinel.

`bls_dataframe_describe` _tool

Optional name describes one registered dataframe; omit it to list active dataframes for the tenant. Requires CANVAS_PROVIDER_TYPE=duckdb.
Returns source tool, query params, row count, TTL (created_at/expires_at), and column_schema; BLS columns are nullable. Registered-query types outside the canvas set (DECIMAL, HUGEINT, SMALLINT, lists) report as VARCHAR. Expired entries are removed when their canvas drop succeeds.

`bls_dataframe_query` _tool

Run one SELECT against registered tables, with JOINs, aggregates, window functions, or CTEs. row_limit defaults to 1000 and caps at 10000; writes, external-file reads, and system catalogs are denied.
Returns rows without consuming BLS API quota. Optional register_as stages the result with a fresh TTL for chained analysis; requires CANVAS_PROVIDER_TYPE=duckdb.

`bls_dataframe_drop` _tool

Required name identifies the dataframe to drop. Available only with CANVAS_PROVIDER_TYPE=duckdb and BLS_DATAFRAME_DROP_ENABLED=true; TTL handles cleanup by default.
Returns dropped: false for a missing table. A failed drop returns retryable canvas_drop_failed and leaves the dataframe registered.

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

BLS-specific:

BLS API v2 client with retry/backoff and daily quota tracking
Offline series catalog search against LABSTAT flat files, indexed as an on-disk SQLite/FTS5 store — zero API quota for discovery; the OES/OEWS wage survey (~6M series) is opt-in via BLS_CATALOG_INCLUDE_OES
Typed error contracts for BLS-specific failure modes — quota exhaustion, locked database, calculations not supported
Period-over-period net/percent-change calculations via BLS's own server-side flag, consistent with BLS's published numbers
Optional DataCanvas spillover (DuckDB) for large multi-series result sets — schema discovery and SQL access without re-querying the API

Agent-friendly output:

Provenance — canvas-spilled results carry a dataset.name handle plus row count and expiry; bls_search_series echoes effectiveQuery, catalogSize, and whether the FTS candidate pool was capped
Graceful partial failure — bls_get_latest returns per-item failed[] (seriesId + error) alongside successful results[] instead of failing the whole batch; bls_get_series keeps valid series when another SeriesID in the same batch is invalid or empty
Discriminated outputs — every observation carries an available boolean for BLS's - missing-value sentinel, so callers branch on a typed field instead of parsing raw values
Actionable notices — enrichment.notice explains empty results, canvas spillover, and unavailable data with concrete next steps (e.g. using bls_search_series to verify a SeriesID)

Getting started

Public Hosted Instance

A public instance is available at https://bls-labor.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

json

{
  "mcpServers": {
    "bls-labor-mcp-server": {
      "type": "streamable-http",
      "url": "https://bls-labor.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file. A free BLS API key unlocks 500 queries/day — register at bls.gov/developers. The server works without a key at 25 req/day.

json

{
  "mcpServers": {
    "bls-labor-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/bls-labor-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "BLS_API_KEY": "your-key-here"
      }
    }
  }
}

Or with npx (no Bun required):

json

{
  "mcpServers": {
    "bls-labor-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/bls-labor-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "BLS_API_KEY": "your-key-here"
      }
    }
  }
}

Or with Docker:

json

{
  "mcpServers": {
    "bls-labor-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "-e", "BLS_API_KEY=your-key-here", "ghcr.io/cyanheads/bls-labor-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_SESSION_MODE=stateless MCP_HTTP_PORT=3010 BLS_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

Bun v1.4.0 or higher (or Node.js v24+).
A free BLS API v2 key — register at bls.gov/developers. Grants 500 queries/day; the server also works without a key at 25 req/day.

Installation

Clone the repository:

git clone https://github.com/cyanheads/bls-labor-mcp-server.git

Navigate into the directory:

cd bls-labor-mcp-server

Install dependencies:

bun install

Configure environment:

cp .env.example .env
# edit .env and set BLS_API_KEY

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts.

Variable	Description	Default
`BLS_API_KEY`	BLS v2 API key. Optional — 25 req/day without, 500 req/day with. Register free at bls.gov/developers.	—
`BLS_BASE_URL`	BLS API v2 base URL.	`https://api.bls.gov/publicAPI/v2`
`BLS_CATALOG_BASE_URL`	LABSTAT flat-file base URL. Override to point at a local mirror.	`https://download.bls.gov/pub/time.series`
`BLS_CATALOG_DB_PATH`	On-disk SQLite catalog index — queried on demand and persisted across restarts. Empty uses an in-memory DB (re-harvested each boot). Mount a volume here in containers.	`.cache/bls-catalog.db`
`BLS_CATALOG_CACHE_TTL_HOURS`	Catalog freshness window in hours — re-harvest once the index is older, checked at startup and hourly while running.	`168` (7 days)
`BLS_CATALOG_INCLUDE_OES`	Include the OES/OEWS wage survey (~6M series / ~1.2 GB; multi-minute first harvest). Off by default — OES series stay fetchable by ID.	`false`
`BLS_OBSERVATIONS_MIRROR_ENABLED`	Serve observations from a local SQLite mirror instead of the live API (requires a one-time bootstrap — see below).	`false`
`BLS_DATASET_TTL_SECONDS`	Per-dataframe TTL for canvas-registered tables, in seconds.	`86400` (24 h)
`BLS_DATAFRAME_DROP_ENABLED`	Expose `bls_dataframe_drop`. TTL handles cleanup by default.	`false`
`CANVAS_PROVIDER_TYPE`	Set to `duckdb` to enable DataCanvas tabular spillover for large result sets.	`none`
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`.	`stdio`
`MCP_HTTP_PORT`	HTTP server port.	`3010`
`MCP_SESSION_MODE`	Session mode. This server uses `stateless`; valid schema values are `auto`, `stateful`, and `stateless`. Schema-default `auto` resolves to `stateful`.	`stateless`
`MCP_AUTH_MODE`	Auth mode: `none`, `jwt`, or `oauth`.	`none`
`MCP_LOG_LEVEL`	Log level (RFC 5424).	`info`
`LOGS_DIR`	Directory for log files (Node.js only).	`<project-root>/logs`
`OTEL_ENABLED`	Enable OpenTelemetry instrumentation.	`false`
`OTEL_EXPORTER_OTLP_ENDPOINT`	Base OTLP URL for traces and metrics; signal-specific endpoints override it.	—
`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	Opt-in OTLP log endpoint. The base URL never enables log export.	—
`LOG_TOOL_FAILURE_PAYLOADS`	Log failed-call arguments and results, redacted by key name; secrets in free-form values remain.	`false`
`LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES`	UTF-8 byte cap per logged failure payload.	`16384`

See .env.example for the full list of optional overrides.

Observation mirror (optional)

For high-volume workloads, an opt-in local mirror serves bls_get_series / bls_get_latest from an embedded SQLite store instead of the BLS API — eliminating the 500/day quota cap. It is off by default. To enable:

Set BLS_OBSERVATIONS_MIRROR_ENABLED=true (and review the BLS_OBSERVATIONS_MIRROR_* vars in .env.example).
Run the one-time bootstrap out-of-band — it downloads the full LABSTAT observation set and can take a while:
sh
```
node dist/services/bls-observations/subprocess.js --init
```

The mirror harvests every survey in the catalog's survey list — OE included, whatever BLS_CATALOG_INCLUDE_OES says — so it covers CM and CI too (about 55 MB of cm.data.* / ci.data.* files). An incremental refresh reads only files published after the mirror's last one, so a mirror bootstrapped before CM and CI joined picks each file up at its next BLS publication; until then those series come from the live API when fallback is on. Until the bootstrap completes, requests fall back to the live API (unless BLS_OBSERVATIONS_MIRROR_FALLBACK_LIVE=false). When a live fallback fails — quota exhausted, BLS unreachable — the series the mirror served are still returned, and enrichment.notice names each unserved SeriesID with the failure's reason and recovery. Mirror rows carry no BLS calculations: with calculations: true, a mirror-served series comes back without calculation fields, enrichment.calculationsApplied is false, and the notice names it. On HTTP transport, an incremental refresh runs on the BLS_OBSERVATIONS_MIRROR_REFRESH_CRON schedule. In containers, mount a persistent volume at BLS_OBSERVATIONS_MIRROR_PATH.

Upgrading an existing mirror. A mirror bootstrapped before sentinel rows were stored is missing the periods BLS publishes with its - missing-value marker. Opening such a mirror clears its sync checkpoint once, so the next refresh re-reads every LABSTAT file and fills them in — no operator action beyond letting that refresh run, and it takes as long as a full read. The mirror keeps serving throughout.

Running the server

Local development

Build and run:

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

Run checks and tests:

bun run devcheck   # Lint, format, typecheck, security
bun run test       # Vitest test suite
bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t bls-labor-mcp-server .
docker run --rm -e BLS_API_KEY=your-key -e MCP_TRANSPORT_TYPE=http -p 3010:3010 bls-labor-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/bls-labor-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Directory	Purpose
`src/index.ts`	`createApp()` entry point — registers tools and initializes services.
`src/config`	Server-specific environment variable parsing and validation with Zod.
`src/mcp-server/tools`	Tool definitions (`*.tool.ts`).
`src/services/bls-api`	BLS API v2 service — batch fetch, latest-value GET, surveys metadata.
`src/services/bls-catalog`	LABSTAT flat-file catalog — offline series index and search.
`src/services/bls-observations`	Optional LABSTAT observation mirror — embedded SQLite store, ingester, and refresh subprocess.
`src/services/bls-periods`	Annual-average period semantics (`M13`/`Q05`/`S03`) shared by the API and mirror paths.
`src/services/canvas-bridge`	DataCanvas bridge — dataframe registration, SQL gate, lifecycle management.
`docs/design.md`	Full tool surface specification, service architecture, and error contracts.
`tests/`	Unit and integration tests mirroring `src/`.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
bls_search_series is the anchor tool — design workflows to call it before the API tools
Wrap BLS API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Install

Tools (6)

bls_list_surveysbls_search_seriesbls_get_latestbls_get_seriesbls_dataframe_describebls_dataframe_query

Configuration

Environment variables

BLS_API_KEY

Optional — works without one (25 req/day). With key: 500 req/day + calculations and annual averages. Register free at bls.gov/developers.

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "bls-labor-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/bls-labor-mcp-server@0.5.7",
        "run",
        "start:stdio"
      ],
      "env": {
        "BLS_API_KEY": "<YOUR_BLS_API_KEY>",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

bls_list_surveys

bls_search_series

bls_get_latest

bls_get_series

bls_dataframe_describe

bls_dataframe_query

@cyanheads/bls-labor-mcp-server

Overview

Tools

Capability reference

bls_list_surveys tool

bls_search_series tool

bls_get_series tool

bls_get_latest tool

bls_dataframe_describe tool

bls_dataframe_query tool

bls_dataframe_drop tool

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Observation mirror (optional)

Running the server

Local development

Docker

Project structure

Development guide

Contributing

License

Install

Configuration

Related servers

`bls_list_surveys` _tool

`bls_search_series` _tool

`bls_get_series` _tool

`bls_get_latest` _tool

`bls_dataframe_describe` _tool

`bls_dataframe_query` _tool

`bls_dataframe_drop` _tool