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

Capability reference

bls_list_surveys _tool

• Optional category filters survey programs by subject; returns codes, names, and calculation-support flags (allowsNetChange, allowsPercentChange, hasAnnualAverages). Each row's searchCoverage (indexed, composed, or none) says whether bls_search_series reaches the survey, with seriesIndexed for indexed ones.
• Backed by the BLS surveys API with 30-day process-local 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, and seasonal_adjustment; blank filters are omitted. area takes a USPS or 2-digit FIPS state code; a 3-, 4-, 5-, or 7-digit CSA, CPI area, county or CBSA, or state + place code; otherwise a substring of area, title, or SeriesID (all-digit values outside those lengths add a notice). limit defaults to 10 and requests above 50 clamp to 50 with notice, with offset pagination. Exact SeriesIDs rank first, then series matching every query word, with any place the query names in full ahead of the rest; at equal score, current series rank first, then national ones, then the JOLTS aggregate.
• 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. Under survey: "OE" without those rows, it composes OEWS SeriesIDs from the OE code tables, up to 50 per search; each is marked composed: true and is unconfirmed until bls_get_series returns data for it. Unindexed surveys remain fetchable by SeriesID.

bls_get_series _tool

• Fetch up to 25 SeriesIDs without an API key or 50 with one 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 local-catalog titles when available and optional BLS measure metadata, and observations with available; preserves the raw - missing-value sentinel, and keeps valid series in mixed batches. Enrichment reports the applied year window, calculations actually returned, annual-summary rows, and any upstream reductions or advisories.
• SeriesIDs are trimmed, uppercased, and deduplicated before the cap; unprocessedSeriesIds lists the exact ordered remainder without automatic extra batches. Omitted year bounds use BLS's three-calendar-year default, subject to coverage.
• Large results spill to dataset.name. With CANVAS_PROVIDER_TYPE=none, all fetched observations return inline.

bls_get_latest _tool

• Fetch the latest observation for up to 50 SeriesIDs (recommended ≤10). IDs are trimmed, uppercased, and deduplicated before the cap; unprocessedSeriesIds lists the exact ordered remainder. Each processed 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. Unavailable when CANVAS_PROVIDER_TYPE=none.
• Returns source tool, query params, row count, TTL (created_at/expires_at, fixed at table creation), 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; larger values clamp to 10000, and preview clamps to the applied row limit with requested/applied notices. Zero preview remains valid; writes, external-file reads, and system catalogs are denied.
• Engine-setting functions (current_setting, current_schema, current_schemas, in_search_path) and query_table are denied. Unqualified current_schema keyword or column references are also denied; qualify a real column with its table alias (for example, t.current_schema). 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. Unavailable when CANVAS_PROVIDER_TYPE=none.

bls_dataframe_drop _tool

• Required name identifies the dataframe to drop. Available only with BLS_DATAFRAME_DROP_ENABLED=true, and never with CANVAS_PROVIDER_TYPE=none; 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
• DataCanvas spillover (DuckDB, on by default) 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 of the LABSTAT files instead of the BLS API, removing the 500/day quota cap; requests fall back to the live API until it is built. Enable it with BLS_OBSERVATIONS_MIRROR_ENABLED=true, then run the one-time bootstrap: node dist/services/bls-observations/subprocess.js --init. Settings, survey coverage, harvest checkpoint and exit codes, fallback and calculation behavior, and upgrade notes are in docs/observation-mirror.md.

Running the server

Local development

• Build and run:

  sh

  # One-time buildbun run rebuild
  # Run the built serverbun run start:stdio# orbun run start:http

• Run checks and tests:

  sh

  bun run devcheck   # Lint, format, typecheck, securitybun run test       # Vitest test suitebun 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 devcheckbun run test

License

Apache-2.0 — see LICENSE for details.