bls-economic-mcp

Official government economic data in your AI assistant — no more hallucinated statistics.

---

What Is This?

When an AI assistant is asked "what is the current unemployment rate?" or "how much has inflation changed over the last year?", it has two options: hallucinate a number from training data, or tell the user it doesn't know. Neither is acceptable for professional use. The Bureau of Labor Statistics publishes the authoritative source for US economic statistics — unemployment, CPI, payrolls, wages, inflation, job openings, producer prices, and productivity — updated on a fixed monthly release calendar. But BLS's public API requires knowing series IDs, handling registration keys, and writing pagination logic before you get a single data point.

This actor provides a named-indicator interface to BLS time series data — request unemployment_rate or cpi_all_urban by name, or supply raw BLS series IDs directly for advanced use cases. Supports change calculations (1-month, 3-month, and 12-month percent change) computed automatically from the series history. Returns structured output with series ID, human-readable label, date, value, and unit — ready to display, analyze, or feed a downstream model. All data comes directly from the BLS public API and reflects the most recent published release.

It runs in Batch mode for economic data pipelines and dashboards, and MCP server mode for live economic data inside Claude Desktop or any MCP-compatible AI assistant. Economists and financial analysts use it to pull current and historical macro data on demand. News organizations use it to verify statistics before publication. AI developers use it to ground their assistants in real, cited government data — eliminating hallucinated statistics from economic conversations entirely.

---

Who Uses This

Financial Analysts and Portfolio Managers You're preparing a macro briefing for an investment committee. You need current unemployment, CPI, core CPI, and nonfarm payrolls — all from the most recent BLS release — in a single structured pull. You also need 12-month change calculations to show the trend. This actor returns all of it in one batch call, labeled and dated, in under 5 seconds.

AI Developer / Chatbot Builder You're building an AI assistant for a financial services firm. The assistant needs to answer questions about current economic conditions using real data. Without a live data integration, your assistant will either hallucinate or refuse to answer. This actor's MCP interface gives your agent access to official BLS statistics on demand — every answer is grounded in the actual published figure, with the date of the release.

Economists and Research Analysts You need 10 years of monthly CPI data to run an inflation analysis, plus JOLTS job openings data for a labor market model. BLS's public data query tool works but requires navigating a multi-step form. This actor returns both series in a single structured call — ready to load into Python, R, or a spreadsheet without any data cleaning.

News Organizations and Economic Journalists Your style guide requires that every economic statistic be sourced and verified before publication. When a reporter references "the unemployment rate" or "year-over-year inflation," you need a fast way to check the actual BLS figure and the release date. This actor gives your fact-checking desk a live lookup with source attribution in seconds.

Enterprise Procurement and Compensation Teams You need current Employment Cost Index (ECI) and Producer Price Index (PPI) data to benchmark salary adjustments and vendor contract escalators. These are official BLS series with specific release schedules. This actor gives you the latest values with date stamps — no navigating the BLS website, no waiting for an analyst to pull it.

---

Key Features

Feature	Detail
Named indicators	Request data by common name — no BLS series ID required
Raw series ID support	Supply any BLS series ID directly for advanced queries
Coverage	Unemployment, CPI (all items + core), Nonfarm Payrolls, Average Hourly Earnings, JOLTS (job openings, hires, quits), PPI, ECI, Productivity, Real Earnings
Change calculations	1-month, 3-month, 12-month percent change computed automatically
Historical depth	Up to 20 years of monthly data (series-dependent)
Multi-series	Fetch up to 25 series in a single call
Date filtering	Specify start/end year to limit time range
Frequency	Monthly, quarterly, and annual series all supported
Data source	BLS Public Data API v2 (official)
MCP server mode	Live tool-use in Claude Desktop, Claude Code, any MCP client
Batch mode	One-shot pipeline runs for dashboards and reports
Unit labels	All values include unit (rate %, thousands of persons, index, $/hour, etc.)

---

Quick Start

Batch Mode — Named Indicators

Input:

{
  "mode": "batch",
  "indicators": [
    "unemployment_rate",
    "cpi_all_urban",
    "cpi_core",
    "nonfarm_payrolls",
    "average_hourly_earnings"
  ],
  "calculate_changes": ["1m", "12m"],
  "periods": 13
}

Output:

[
  {
    "series_id": "LNS14000000",
    "series_label": "Unemployment Rate, Seasonally Adjusted",
    "indicator_name": "unemployment_rate",
    "unit": "percent",
    "latest": {
      "year": "2025",
      "period": "M04",
      "date": "2025-04-01",
      "value": 4.2
    },
    "changes": {
      "change_1m": -0.1,
      "change_1m_pct": -2.33,
      "change_12m": 0.3,
      "change_12m_pct": 7.69
    },
    "history": [
      {"date": "2025-04-01", "value": 4.2},
      {"date": "2025-03-01", "value": 4.3},
      {"date": "2025-02-01", "value": 4.2},
      {"date": "2025-01-01", "value": 4.1}
    ]
  },
  {
    "series_id": "CUSR0000SA0",
    "series_label": "CPI for All Urban Consumers (CPI-U), Seasonally Adjusted",
    "indicator_name": "cpi_all_urban",
    "unit": "index (1982-84=100)",
    "latest": {
      "year": "2025",
      "period": "M04",
      "date": "2025-04-01",
      "value": 316.8
    },
    "changes": {
      "change_1m": 0.2,
      "change_1m_pct": 0.06,
      "change_12m": 9.2,
      "change_12m_pct": 2.99
    }
  }
]

Batch Mode — Raw Series IDs

Input:

{
  "mode": "batch",
  "series_ids": ["JTS000000000000000JOL", "JTS000000000000000HIL", "JTS000000000000000QUL"],
  "start_year": 2020,
  "end_year": 2025,
  "calculate_changes": ["12m"]
}

MCP Server Mode

{
  "mcpServers": {
    "bls-economic": {
      "command": "npx",
      "args": [
        "apify-actor-mcp",
        "--actor-id", "your-username/bls-economic-mcp",
        "--token", "YOUR_APIFY_TOKEN"
      ]
    }
  }
}

Then in Claude: "What is the current US unemployment rate and how has it changed over the last 12 months? Use official BLS data."

---

MCP Tools Exposed

get_economic_indicators

Fetch current values and history for named economic indicators.

{
  "tool": "get_economic_indicators",
  "arguments": {
    "indicators": ["unemployment_rate", "cpi_all_urban", "nonfarm_payrolls"],
    "calculate_changes": ["1m", "3m", "12m"],
    "periods": 24
  }
}

get_series

Fetch any BLS time series by series ID — for advanced users who know specific BLS identifiers.

{
  "tool": "get_series",
  "arguments": {
    "series_ids": ["CES0000000001", "LNS14000000"],
    "start_year": 2015,
    "end_year": 2025
  }
}

get_inflation_detail

Return a full inflation breakdown — CPI all items, core CPI, shelter, food at home, energy, and new/used vehicles — for the current month and 12-month change.

{
  "tool": "get_inflation_detail",
  "arguments": {
    "calculate_changes": ["1m", "12m"]
  }
}

get_labor_market_snapshot

Return a comprehensive labor market summary — unemployment, participation rate, payrolls, AHE, JOLTS — in a single call optimized for briefing documents.

{
  "tool": "get_labor_market_snapshot",
  "arguments": {
    "periods": 12,
    "calculate_changes": ["1m", "12m"]
  }
}

get_historical_series

Return a long historical series (up to 20 years) for a single named indicator.

{
  "tool": "get_historical_series",
  "arguments": {
    "indicator": "cpi_all_urban",
    "start_year": 2005,
    "end_year": 2025
  }
}

---

Named Indicator Reference

Indicator Name	BLS Series ID	Description	Frequency
unemployment_rate	LNS14000000	Unemployment Rate, Seasonally Adjusted	Monthly
labor_force_participation	LNS11300000	Labor Force Participation Rate, SA	Monthly
cpi_all_urban	CUSR0000SA0	CPI-U, All Items, Seasonally Adjusted	Monthly
cpi_core	CUSR0000SA0L1E	CPI-U, All Items Less Food & Energy, SA	Monthly
cpi_shelter	CUSR0000SAH1	CPI-U, Shelter	Monthly
cpi_food_at_home	CUSR0000SAF11	CPI-U, Food at Home	Monthly
cpi_energy	CUSR0000SA0E	CPI-U, Energy	Monthly
ppi_final_demand	WPUFD49104	PPI, Final Demand	Monthly
nonfarm_payrolls	CES0000000001	Total Nonfarm Payrolls, SA (thousands)	Monthly
private_payrolls	CES0500000001	Private Nonfarm Payrolls, SA	Monthly
average_hourly_earnings	CES0500000003	Avg Hourly Earnings, Private, SA ($/hr)	Monthly
average_weekly_hours	CES0500000002	Avg Weekly Hours, Private, SA	Monthly
jolts_job_openings	JTS000000000000000JOL	JOLTS Job Openings (thousands)	Monthly
jolts_hires	JTS000000000000000HIL	JOLTS Hires (thousands)	Monthly
jolts_quits	JTS000000000000000QUL	JOLTS Quits (thousands)	Monthly
eci_wages	CIU2010000000000A	Employment Cost Index, Wages & Salaries	Quarterly
productivity_nonfarm	PRS85006092	Nonfarm Business Productivity, SA	Quarterly
real_earnings_weekly	LES1252881500Q	Real Avg Weekly Earnings, SA	Monthly

---

Input Schema

Field	Type	Default	Description
mode	string	"batch"	"batch" or "mcp"
indicators	array	—	Named indicator strings (see table above)
series_ids	array	—	Raw BLS series IDs (alternative to named indicators)
start_year	integer	current year - 3	Start year for historical data
end_year	integer	current year	End year for historical data
periods	integer	13	Number of periods to return (most recent N)
calculate_changes	array	[]	Change calculations: "1m", "3m", "12m"
seasonally_adjusted	boolean	true	Return SA series where available; set false for NSA
include_annotations	boolean	true	Include BLS footnotes and preliminary flags
bls_api_key	string	—	Optional BLS API key (increases rate limit from 25 to 500 req/day)

---

Use Case Recipes

Recipe 1: Monthly Macro Briefing Package

Complete economic snapshot for an investment committee deck:

{
  "indicators": [
    "unemployment_rate",
    "labor_force_participation",
    "nonfarm_payrolls",
    "average_hourly_earnings",
    "cpi_all_urban",
    "cpi_core",
    "jolts_job_openings",
    "ppi_final_demand"
  ],
  "calculate_changes": ["1m", "12m"],
  "periods": 13
}

Outcome: Complete macro dashboard with current values and 12-month change for every major indicator — formatted and ready for a slide deck or executive briefing.

Recipe 2: Inflation Component Breakdown

Detailed CPI decomposition for a research note:

{
  "indicators": [
    "cpi_all_urban",
    "cpi_core",
    "cpi_shelter",
    "cpi_food_at_home",
    "cpi_energy"
  ],
  "calculate_changes": ["1m", "3m", "12m"],
  "periods": 25
}

Outcome: 2-year monthly history with all change metrics — shows which components are driving headline inflation. Use get_inflation_detail tool in MCP mode for a pre-packaged version.

Recipe 3: Labor Market Historical Analysis

10-year monthly unemployment and payrolls for an academic paper:

{
  "indicators": ["unemployment_rate", "nonfarm_payrolls", "labor_force_participation"],
  "start_year": 2015,
  "end_year": 2025,
  "seasonally_adjusted": true
}

Outcome: 10 years of monthly data spanning COVID, recovery, and post-pandemic tightening — ready to import into R or Python for analysis.

Recipe 4: Wage Pressure Monitoring

Track Employment Cost Index and Average Hourly Earnings together for compensation benchmarking:

{
  "indicators": ["eci_wages", "average_hourly_earnings", "real_earnings_weekly"],
  "calculate_changes": ["3m", "12m"],
  "periods": 20
}

Outcome: Wage trend data from two complementary BLS measures — use for contract escalator negotiations, salary planning, or macroeconomic research.

---

Connecting to Claude Desktop / Claude Code

Claude Desktop:

{
  "mcpServers": {
    "bls-economic": {
      "command": "npx",
      "args": [
        "apify-actor-mcp",
        "--actor-id", "your-username/bls-economic-mcp",
        "--token", "apify_api_YOURTOKEN"
      ],
      "env": {}
    }
  }
}

Claude Code:

{
  "mcpServers": {
    "bls-economic": {
      "command": "npx",
      "args": ["apify-actor-mcp", "--actor-id", "your-username/bls-economic-mcp", "--token", "apify_api_YOURTOKEN"]
    }
  }
}

The key benefit in MCP mode: Claude will stop guessing at economic statistics. Instead of a hallucinated figure from training data, every economic claim is backed by a live BLS pull with the exact release date. Responses read as: "According to the BLS, the unemployment rate for April 2025 was 4.2%, up 0.3 percentage points from April 2024." — sourced, dated, and accurate.

Sample prompts once connected:

• "What is the current US unemployment rate?"
• "How much has inflation changed over the last 12 months? Break it down by CPI component."
• "Pull the last 2 years of JOLTS job openings data."
• "What's the current Employment Cost Index and how does it compare to a year ago?"

---

Pricing

Volume	Price
First 1,000 results	$0.50
1,001 – 50,000 results	$0.40/1k
50,000+ results	$0.30/1k

Note: Each named indicator per batch call counts as one result-row per time period returned. A 13-period pull of 8 indicators = 104 rows.

ROI context: Bloomberg Economic data terminal access costs $2,000–$5,000/month. Economic data subscriptions from Haver Analytics, Refinitiv, or Moody's Analytics run similar figures. This actor provides BLS's own official data — the primary source those platforms aggregate — at a fraction of the cost. For an AI assistant that answers 50 economic questions per day with live data, monthly cost is under $5.

---

Data Source and Freshness

• Primary: BLS Public Data API v2 — api.bls.gov/publicAPI/v2/timeseries/data/
• Data authority: Bureau of Labor Statistics, US Department of Labor — the primary source for US employment, inflation, and wage statistics
• Update frequency: Data reflects the most recent BLS published release; the actor queries BLS directly on each request (no cached intermediary)
• Release calendar: BLS publishes on a fixed monthly schedule (e.g., CPI releases on the 2nd or 3rd week; Employment Situation on the first Friday of the month)
• Preliminary flags: First-release figures are flagged as preliminary where BLS marks them; revisions are reflected as BLS publishes them
• Series availability: Not all series extend the full 20 years; series start dates vary by indicator

---

Technical Notes

• By default, the actor uses the unauthenticated BLS API (25 requests/day limit). For high-volume batch use, supply your own free BLS API key via the bls_api_key input field — registration is free at bls.gov/developers
• Named indicators map to the seasonally adjusted series by default; set seasonally_adjusted: false to request NSA series (note: not all indicators have NSA variants)
• Change calculations are computed from the series history — 1m is value vs. prior month, 12m is value vs. same period prior year
• Quarterly series (ECI, Productivity) return fewer data points per year; periods: 13 for a quarterly series returns ~3 years of data
• The value field is always a float in the indicator's native unit (percent, index, thousands, $/hour)
• Preliminary data flags are included in the annotations field when include_annotations: true
• BLS rate limits apply; the actor implements automatic retry with backoff for 429 responses

---

Support

• Issues: File a GitHub issue on the actor repository
• Apify Community: community.apify.com
• BLS Public Data API docs: www.bls.gov/developers/api_signature_v2.htm
• BLS series finder: www.bls.gov/data
• BLS release calendar: www.bls.gov/schedule/news_release/releaseCalendar.htm
• Free BLS API key registration: data.bls.gov/registrationEngine