Bls Labor MCP Server README

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

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.

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:

   shCopy

   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:

  shCopy

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• Run checks and tests:

  shCopy

  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

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.