
bls-labor-mcp-server
io.github.cyanheads/bls-labor-mcp-server
Fetch US Bureau of Labor Statistics data — CPI, unemployment, wages, JOLTS, and more via MCP.
Documentation
@cyanheads/bls-labor-mcp-server
Fetch US Bureau of Labor Statistics data — CPI, unemployment, wages, JOLTS, and more via MCP. STDIO or Streamable HTTP.
Public Hosted Server: https://bls-labor.caseyjhand.com/mcp
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. Unavailable when CANVAS_PROVIDER_TYPE=none. |
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. Unavailable when CANVAS_PROVIDER_TYPE=none. |
bls_dataframe_drop | Drop a canvas dataframe by name. Available when BLS_DATAFRAME_DROP_ENABLED=true, unless CANVAS_PROVIDER_TYPE=none; TTL handles cleanup by default. |
Capability reference
bls_list_surveys tool
- Optional
categoryfilters survey programs by subject; returns codes, names, and calculation-support flags (allowsNetChange,allowsPercentChange,hasAnnualAverages). Each row'ssearchCoverage(indexed,composed, ornone) says whetherbls_search_seriesreaches the survey, withseriesIndexedfor indexed ones. - Backed by the BLS surveys API with 30-day process-local caching. Annual-average support is advisory; read
bls_get_series'sannualAverageRowsfor the rows actually returned.
bls_search_series tool
- Search by text or SeriesID, with optional
survey,area, andseasonal_adjustment; blank filters are omitted.areatakes 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).limitdefaults to 10 and requests above 50 clamp to 50 with notice, withoffsetpagination. Exact SeriesIDs rank first, then series by how many query words they match (a concept alias such asinflationorwagecounts for every series of its survey), with any place the query names in full first among the series matching every word; at equal score, current series rank first, then national ones, then a survey's aggregate (the JOLTS Total nonfarm, ECEC and ECI totals, BED total private, and CPI All items rows) ahead of its breakdowns. - Returns decoded SeriesIDs, titles,
frequency, and independently optionalstartYear,endYear, andendPeriodcoverage (for example,1982–2005 Q04). Coverage describes the catalog snapshot, not continuous observations. FollownextOffsetwhiletruncatedis true;capped: truemakestotalCounta 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. Undersurvey: "OE"without those rows, it composes OEWS SeriesIDs from the OE code tables, up to 50 per search; each is markedcomposed: trueand is unconfirmed untilbls_get_seriesreturns 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_yearwindow of up to 20 years, optionalcalculations, andannual_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
measuremetadata, and observations withavailable; 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;
unprocessedSeriesIdslists 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. WithCANVAS_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;
unprocessedSeriesIdslists the exact ordered remainder. Each processed ID consumes one API query; usebls_get_seriesfor a more efficient multi-series batch. - Returns successful
results[]beside per-seriesfailed[]entries.latestObservation.availabledistinguishes a published value from BLS's missing-value sentinel.
bls_dataframe_describe tool
- Optional
namedescribes one registered dataframe; omit it to list active dataframes for the tenant. Unavailable whenCANVAS_PROVIDER_TYPE=none. - Returns source tool, query params, row count, TTL (
created_at/expires_at, fixed at table creation), andcolumn_schema; BLS columns are nullable. Registered-query types outside the canvas set (DECIMAL,HUGEINT, lists) report asVARCHAR;TINYINT,SMALLINT,UTINYINT, andUSMALLINTreport asINTEGER, andUINTEGERasBIGINT. 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_limitdefaults to 1000; larger values clamp to 10000, andpreviewclamps 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) andquery_tableare denied. Unqualifiedcurrent_schemakeyword 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_asstages the result with a fresh TTL for chained analysis; a name that matches a DuckDB system catalog or metadata view is refused withregister_as_system_catalog. Unavailable whenCANVAS_PROVIDER_TYPE=none.
bls_dataframe_drop tool
- Required
nameidentifies the dataframe to drop. Available only withBLS_DATAFRAME_DROP_ENABLED=true, and never withCANVAS_PROVIDER_TYPE=none; TTL handles cleanup by default. - Returns
dropped: falsefor a missing table. A failed drop returns retryablecanvas_drop_failedand 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.namehandle plus row count and expiry;bls_search_seriesechoeseffectiveQuery,catalogSize, and whether the FTS candidate pool wascapped - Graceful partial failure —
bls_get_latestreturns per-itemfailed[](seriesId + error) alongside successfulresults[]instead of failing the whole batch;bls_get_serieskeeps valid series when another SeriesID in the same batch is invalid or empty - Discriminated outputs — every observation carries an
availableboolean for BLS's-missing-value sentinel, so callers branch on a typed field instead of parsing raw values - Actionable notices —
enrichment.noticeexplains empty results, canvas spillover, and unavailable data with concrete next steps (e.g. usingbls_search_seriesto 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.4 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 | Per-survey catalog freshness window in hours — a survey re-harvests once its last success is older, and a failed survey's retry backoff is capped at this many hourly checks. Checked at startup and hourly while running. | 168 (7 days) |
BLS_CATALOG_INCLUDE_OES | Include the OES/OEWS wage survey (~6M series / ~1.26 GB; multi-minute first harvest). Off by default — OES series stay fetchable by ID, and search composes them from the small OE code tables. | 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 | DataCanvas provider for tabular spillover of large result sets and the dataframe tools. Set to none to disable them. The Claude Desktop bundle ships without DuckDB and pins none. | duckdb |
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 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:
# 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 | Period-code semantics shared by the API and mirror paths: annual-average codes (M13/Q05/S03) and the live API's period names. |
src/services/canvas-bridge | DataCanvas bridge — dataframe registration, SQL gate, lifecycle management. |
src/services/labstat | Streamed LABSTAT reads (header and per-chunk stall deadlines, line regrouping) shared by the catalog harvest and the observation ingester. |
docs/design.md | Full tool surface specification, service architecture, and error contracts. |
docs/observation-mirror.md | Observation mirror setup, coverage, and upgrade notes. |
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/catchin tool logic - Use
ctx.logfor request-scoped logging,ctx.statefor tenant-scoped storage bls_search_seriesis 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.
@cyanheads/bls-labor-mcp-servernpm install @cyanheads/bls-labor-mcp-server@cyanheads/bls-labor-mcp-servernpm install @cyanheads/bls-labor-mcp-serverRemote
Related Servers
io.github.cyanheads/anime-mcp-server
Search anime/manga, franchise relations, schedule, characters, rankings, studio filmography.
io.github.cyanheads/art-institute-chicago-mcp-server
Search the Art Institute of Chicago collection: artworks, artists, exhibitions, and audio guides.
io.github.cyanheads/arxiv-mcp-server
Search arXiv, fetch paper metadata, and read full-text content.