bls-labor-mcp-server
Server Details
Fetch US Bureau of Labor Statistics data — CPI, unemployment, wages, JOLTS, and more via MCP.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
- Repository
- cyanheads/bls-labor-mcp-server
- GitHub Stars
- 1
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.6/5 across 6 of 6 tools scored.
Each tool serves a distinct purpose: survey listing, series search, data retrieval (single vs. multiple series), and DataFrame inspection/query. No overlapping functionality.
All tools follow the 'bls_' prefix followed by a clear verb_noun pattern in snake_case (e.g., bls_list_surveys, bls_search_series), demonstrating strong consistency.
Six tools cover the full workflow from discovery to analysis without being excessive. Each tool is justified and scoped appropriately for the domain.
The tool surface provides complete coverage for exploring, fetching, and analyzing BLS labor data, including offline search, multiple retrieval modes, and SQL-based analysis on dataframes.
Available Tools
6 toolsbls_dataframe_describeDescribe BLS DataframesARead-onlyIdempotentInspect
List canvas dataframes materialized by bls_get_series, with provenance (source tool, query parameters), TTL, row count, and column schema. Use before writing SQL to confirm column names. Lazy-sweeps expired tables before responding. Requires CANVAS_PROVIDER_TYPE=duckdb.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional table name (df_XXXXX_XXXXX) to describe a single dataframe. Omit to list all active dataframes. |
Output Schema
| Name | Required | Description |
|---|---|---|
| dataframes | Yes | Active dataframes for this tenant, newest first. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint and idempotentHint. Description adds behavioral details: 'Lazy-sweeps expired tables before responding' and environment requirement, providing context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences plus a requirement line. Every sentence adds value, front-loaded with purpose. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (1 optional param, output schema exists), the description covers purpose, usage hint, behavioral side-effect, and environment constraint. Complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description largely repeats the schema's parameter description. No additional semantic value beyond what the input schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'List' and resource 'canvas dataframes materialized by bls_get_series', clearly distinguishing from sibling tools like bls_dataframe_query (which queries) and bls_get_series (which retrieves series).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use before writing SQL to confirm column names' for context, and mentions prerequisite 'Requires CANVAS_PROVIDER_TYPE=duckdb'. Does not explicitly state when not to use, but sibling names imply alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bls_dataframe_queryQuery BLS DataframesARead-onlyIdempotentInspect
Run a single-statement SELECT against the canvas dataframes registered by bls_get_series. 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.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | 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. | |
| preview | No | 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 | No | Hard cap on rows materialized in the response (default 1000, max 10000). Full results live on-canvas under register_as when provided. | |
| register_as | No | 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. |
Output Schema
| Name | Required | Description |
|---|---|---|
| rows | Yes | Materialized rows, bounded by preview / row_limit. |
| columns | Yes | Column names in projection order. |
| row_count | Yes | Total rows the query produced (may exceed rows.length when capped by row_limit). |
| expires_at | No | ISO 8601 expiry for the newly registered dataframe, when applicable. |
| registered_as | No | Set when register_as was supplied and the result was materialized. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint: true and idempotentHint: true, and the description reinforces this with specifics: writes, DDL, DROP, COPY, PRAGMA, ATTACH, external-file table functions rejected, and system catalogs denied. It adds value beyond annotations by listing exactly what operations are blocked and why, ensuring the agent understands constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph of ~8 sentences, efficiently covering the core action, restrictions, capabilities, optional parameter, and performance note. Every sentence adds essential information without redundancy, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown but indicated) and the complexity of a query tool with multiple parameters and restrictions, the description is thorough. It covers read-only nature, disallowed operations, alternative tool for metadata, register_as for chaining, and zero quota impact. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds context for each parameter: e.g., referencing dataframes by names from bls_get_series, explaining preview default and use case, row_limit cap, and register_as persistence. While the schema already provides descriptions, the tool description enhances their interconnection and practical usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Run a single-statement SELECT against the canvas dataframes', specifying the verb and resource. It distinguishes from siblings like bls_dataframe_describe by mentioning it lists available dataframes, and from other BLS tools by focusing on querying existing dataframes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly details when to use the tool (read-only SELECT queries) and what is not allowed (writes, DDL, etc.). It directs users to bls_dataframe_describe for listing dataframes and explains the register_as option for chaining analyses. It also notes zero BLS quota consumption, providing full context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bls_get_latestGet Latest BLS ObservationARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| series_ids | Yes | 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. |
Output Schema
| Name | Required | Description |
|---|---|---|
| failed | Yes | Series that failed to fetch, with per-item error details. |
| results | Yes | Latest observation for each requested series, in request order. |
| succeeded | Yes | Number of series with a successfully fetched observation. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, and idempotentHint. Description adds practical constraints: each series consumes one API query, daily limit of 500, and recommended series count. It doesn't cover error handling or missing series behavior, but adds valuable operational context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first defines function, second provides usage guidance. No wasted words. Front-loaded with core action. Perfectly structured for quick agent understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter, good annotations, and an output schema, the description fully covers usage context, quota, and recommendations. No gaps remain for typical use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage for series_ids. Description expands significantly: explains quota consumption per series, directs to bls_search_series for ID resolution, and reiterates recommended limits. This adds meaning beyond the schema's basic description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the single most recent observation for BLS series, using specific verb + resource. It distinguishes from sibling tools like bls_get_series by noting quota efficiency, making purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use for 'what is X right now' questions, gives examples (unemployment rate, CPI), and advises against using for many series where bls_get_series is more efficient. Also mentions recommended limit of 10 series and max of 50, with quota impact.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bls_get_seriesGet BLS Time-Series DataARead-onlyInspect
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 + percent change together — not individually; not all surveys support it, check bls_list_surveys first). 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 for follow-up SQL via bls_dataframe_query. Use bls_search_series first if you need to resolve a concept to a SeriesID.
| Name | Required | Description | Default |
|---|---|---|---|
| end_year | No | End year for the data range (inclusive). Defaults to the current year when omitted. | |
| series_ids | Yes | 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 | No | Start year for the data range (inclusive). The BLS API allows up to 20 years per request. Omit for the API default (typically 3–20 years depending on survey). | |
| calculations | No | When true, request BLS-computed net change and percent change together (cannot request one independently). Not all surveys support this — check bls_list_surveys first. The API returns an error if requested for an unsupported survey. |
Output Schema
| Name | Required | Description |
|---|---|---|
| series | Yes | Series data, in request order. |
| dataset | No | Canvas dataframe handle — present when the observation volume exceeded the inline budget. Use bls_dataframe_query with dataset.name to run SQL across the full data. |
| spilled | Yes | True when results spilled to canvas due to inline budget overflow. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds that it is a read operation ('fetch'), explains the rate limit implication ('one query against the 500/day limit'), and clarifies the combined nature of calculations and the spill mechanism. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One focused paragraph of about 5 sentences, front-loaded with the main purpose. Every sentence adds necessary context with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers prerequisites (use bls_search_series first), constraints (500/day limit, 20-year range, calculation support), fallback behavior (spill to canvas with dataset.name), and links to sibling tools. The output schema exists so return values need not be detailed. All critical aspects are addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 4 parameters have schema descriptions (100% coverage), but the description adds contextual semantics: e.g., 'entire batch counts as one API query' for series_ids, 'up to 20 years per request' for start_year, and 'cannot request one independently' for calculations. This adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch time-series data for 1–50 BLS series by SeriesID in a single API request', specifying the action (fetch) and resource (time-series data), and distinguishes from siblings like bls_search_series (for resolving concepts) and bls_dataframe_query (for SQL on spilled data).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using bls_search_series first to resolve concepts to SeriesIDs, and bls_list_surveys to check calculation support. It also mentions the 500/day rate limit and the spill-to-canvas behavior for large results, guiding when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bls_list_surveysList BLS SurveysARead-onlyIdempotentInspect
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. Optional category filter narrows results to prices, employment, wages, productivity, injuries, or time_use surveys.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Optional category filter. One of: prices, employment, wages, productivity, injuries, time_use. Omit to list all surveys. |
Output Schema
| Name | Required | Description |
|---|---|---|
| total | Yes | Total surveys returned. |
| surveys | Yes | BLS survey programs matching the filter, sorted alphabetically by abbreviation. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, and openWorldHint=false. The description adds that the tool returns metadata (abbreviation codes, full names, etc.), which is helpful. No contradictions. For a list tool with robust annotations, the description adds adequate context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Information is front-loaded: purpose first, then usage guidance. Highly concise and effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (signaled by context) and annotations cover safety and idempotency, the description completes the picture: it explains purpose, when to use, what parameter does, and what results include. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with the enum values already documented in the schema description. The description reiterates the optional category filter and lists possible values, adding marginal value beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists BLS survey programs with specific metadata (abbreviation codes, full names, calculation support, annual averages). It also explicitly positions this tool as a discovery step before calling bls_search_series, differentiating it from sibling tools like bls_search_series or bls_get_series.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises using this tool to discover surveys before bls_search_series and mentions the optional category filter. While it does not explicitly state when not to use it or list alternatives, the context is clear and sufficient for most use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bls_search_seriesSearch BLS SeriesARead-onlyInspect
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 plain-language names. Use this before bls_get_series when you have a concept but not a SeriesID. Operates offline — no API quota consumed. Survey filter accepts two-letter codes (CU, CE, LN, LA, PC, JT, OE, EC, PR). Area filter accepts state names, MSA names, or FIPS area codes.
| Name | Required | Description | Default |
|---|---|---|---|
| area | No | State name, MSA name, or FIPS area code to narrow results to a geographic area. Omit for national series. | |
| limit | No | Maximum number of results to return (1–50, default 10). | |
| query | Yes | Natural language or keyword query (e.g. "unemployment rate", "CPI food", "nonfarm payrolls"). Also accepts a SeriesID directly for exact lookup. | |
| survey | No | Two-letter LABSTAT survey abbreviation to filter results (e.g. CU for CPI, CE for CES, LN for CPS, LA for LAUS, JT for JOLTS, OE for OEWS). Omit to search all loaded surveys. | |
| seasonal_adjustment | No | When true, return only seasonally adjusted series. When false, return only not-seasonally-adjusted. Omit to return both. |
Output Schema
| Name | Required | Description |
|---|---|---|
| total | Yes | Total matches in the catalog before the limit was applied. |
| series | Yes | Matching series, ordered by relevance. |
| catalogSize | Yes | Total series in the loaded catalog index. Used to distinguish an empty-result search from a failed catalog load. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and openWorldHint. The description adds value by stating it operates offline, consumes no API quota, and returns decoded components with plain-language names. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three well-structured sentences: purpose, usage guidance, and filter specifics. No redundant words; all information is essential and placed prominently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
All parameters are covered in schema with 100% description coverage, and the description adds critical usage guidelines, behavioral notes (offline, no quota), and filter details. With an output schema present, return value explanation is unnecessary. The description is fully adequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, baseline is 3. The description enriches parameter understanding by listing examples for survey codes (CU, CE, etc.) and area filter options (state names, MSA names, FIPS codes), going beyond the schema's generic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: searching the BLS series catalog by natural language query, survey code, geographic area, or keywords to resolve cryptic SeriesIDs. It also distinguishes itself from the sibling tool bls_get_series by specifying when to use it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using this tool before bls_get_series when you have a concept but not a SeriesID, and mentions it operates offline with no API quota. Provides specific details on survey and area filters, but does not exhaustively list all alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!