bls-mcp-server

---

Overview

US labor statistics from the Bureau of Labor Statistics: jobs, unemployment, wages, and inflation. Find series in plain language instead of decoding SeriesIDs, pull full history or the latest value, and run SQL over large multi-series results.

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, place names prefer matching decoded areas; national series win equal-score ties within each preference group. Exact SeriesIDs rank first.
• Returns decoded SeriesIDs, titles, frequency, and independently optional startYear, endYear, and endPeriod coverage (for example, 1982–2005 Q04). Coverage describes the catalog snapshot, not continuous observations. 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.
• Engine settings (current_setting, current_schema, current_schemas, in_search_path) and query_table are denied. query() accepts one plain SQL string literal, checked recursively up to four levels; computed SQL strings are rejected. Reference staged tables directly for analysis.
• 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:

{
  "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.

{
  "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):

{
  "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:

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

1. Clone the repository:

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

2. Navigate into the directory:

cd bls-labor-mcp-server

3. Install dependencies:

bun install

4. 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:

1. Set BLS_OBSERVATIONS_MIRROR_ENABLED=true (and review the BLS_OBSERVATIONS_MIRROR_* vars in .env.example).

2. Run the one-time bootstrap out-of-band — it downloads the full LABSTAT observation set and can take a while:

   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.