fred-economic-mcp

30+ Federal Reserve FRED economic indicators, live in your AI assistant. No API key required.

---

What Is This?

The St. Louis Federal Reserve's FRED (Federal Reserve Economic Data) database contains 800,000+ economic time series from 100+ international, national, and regional sources. It is the definitive source for US macroeconomic data: unemployment rate, CPI, GDP, federal funds rate, Treasury yields, housing starts, retail sales, M2 money supply, the yield curve, and every other indicator that economists and traders track.

FRED is free to access — but its REST API requires registration, its website is not queryable by AI assistants, and integrating it into automated workflows requires building an API client, handling authentication, managing pagination, and normalizing varying data formats across series.

This actor solves all of that. It exposes 30+ curated FRED series via four MCP tools — with zero API key required. Data is fetched via FRED's public CSV graph endpoint (https://fred.stlouisfed.org/graph/fredgraph.csv?id=SERIES_ID) which is unauthenticated, returns clean 2-column CSV (date, value), and covers the full FRED history for any series. In MCP server mode, Claude can answer "What's the current yield curve? Is it still inverted?" by fetching T10Y2Y live and returning the latest spread — without leaving the conversation.

For series not in the curated catalog, the get_indicator_by_series_id tool accepts any raw FRED series ID — so the full 800,000+ series catalog is reachable.

---

Who Uses This

Macro Traders and Portfolio Managers You need to know the current state of the 10Y-2Y yield curve before a rates trade. You want to compare CPI and PCE inflation on the same chart. You need to check whether jobless claims came in above or below the recent trend before entering a risk position. This actor gives you all of those in a single Claude conversation — no Bloomberg terminal required.

Equity Research Analysts You're building a DCF model and need to anchor your discount rate to the current 10-year Treasury. You're writing a consumer sector note and need recent retail sales data and consumer confidence readings. You're modeling a housing company and need housing starts, existing home sales, and the 30-year mortgage rate in the same pull. One call to compare_indicators returns all of them.

Startup Founders Writing Investor Materials You need to ground your pitch in macroeconomic context — GDP growth rate, inflation trend, employment conditions. This actor gives you current FRED data formatted for easy citation in a deck or memo, without paying for an economic data subscription.

Economists and Policy Researchers You're analyzing the 2022–2024 inflation cycle and need CPI, core CPI, PCE, and PPI going back 36 months on the same timeline. You're studying the yield curve's predictive power and need the full T10Y2Y history. The get_indicator_by_series_id tool gives you any of FRED's 800,000+ series — the entire database is accessible, not just the curated 30.

Financial Journalists You're writing about the Fed's rate policy and need the federal funds rate history since 2022. You're covering the housing market and need housing starts, mortgage rates, and home prices in the same conversation. This actor fetches them all — with trend calculations (period change, year-over-year) already computed.

Developers Building Economic Dashboards You want to build a macro dashboard inside a Claude or LLM-powered product without managing FRED API authentication and parsing. Use this actor in MCP server mode as your data backend — your application calls MCP tools, gets structured JSON back, and renders it however you need.

---

Key Features

Feature	Detail
Series catalog	30+ curated FRED series across 7 categories
Custom series	Any of FRED's 800,000+ series via raw series ID
No API key	Uses FRED's public CSV endpoint — no registration required
Trend analysis	Auto-computes latest value, period change, YoY change, min/max/avg
Concurrent fetching	compare_indicators fetches all series in parallel
MCP server mode	Live tool-use in Claude Desktop, Claude Code, any MCP client
Batch mode	One-shot runs with structured dataset output
Coverage	Full FRED history for all series (1947+ for some series)
Frequency support	Daily, weekly, monthly, quarterly series all supported

Indicator Categories

Category	Indicators
Labor	Unemployment rate, nonfarm payrolls, initial claims, JOLTS openings, participation rate
Inflation	CPI, core CPI, PCE price index, PPI
GDP & Output	Nominal GDP, real GDP, GDP growth rate, industrial production, capacity utilization
Interest Rates	Fed funds rate, 10Y Treasury, 2Y Treasury, 3M Treasury, yield curve (T10Y2Y), 30Y mortgage
Housing	Housing starts, Case-Shiller HPI, existing home sales
Consumer	Retail sales, PCE, UMich consumer sentiment
Money & Credit	M2 money supply, credit card interest rate
Trade & Markets	Trade balance, USD index, S&P 500, VIX

---

Quick Start

Batch Mode — Default Macro Dashboard

Run with empty input to get the 5 core macro indicators (unemployment, CPI, fed funds rate, GDP growth, yield curve):

Input:

{}

Output (one record per indicator):

[
  {
    "series_id": "UNRATE",
    "indicator_name": "unemployment",
    "name": "Unemployment Rate",
    "latest_value": 3.9,
    "latest_date": "2024-03-01",
    "change_from_previous": -0.1,
    "change_pct_from_previous": -2.5,
    "change_pct_yoy": 0.2,
    "units": "%",
    "frequency": "monthly",
    "category": "labor",
    "periods_returned": 24,
    "source": "fred.stlouisfed.org"
  },
  {
    "series_id": "T10Y2Y",
    "indicator_name": "yield_curve",
    "name": "10Y-2Y Treasury Yield Spread",
    "latest_value": -0.37,
    "latest_date": "2024-04-15",
    "change_from_previous": 0.04,
    "change_pct_from_previous": -9.8,
    "change_pct_yoy": -0.81,
    "units": "%",
    "frequency": "daily",
    "category": "rates",
    "periods_returned": 24,
    "source": "fred.stlouisfed.org"
  }
]

Batch Mode — Custom Indicator Set

Input:

{
  "indicators": ["housing_starts", "mortgage_30y", "home_price_index"],
  "periods": 36
}

Returns 36 months of housing sector data with trend stats.

Batch Mode — Raw FRED Series ID

Input:

{
  "seriesId": "WALCL",
  "periods": 24
}

Returns 24 data points for WALCL (Fed Balance Sheet — Assets, Weekly Wednesday Level).

Full Observations for a Single Indicator

Input:

{
  "indicators": ["cpi"],
  "periods": 60
}

Returns 60 months (5 years) of CPI data with all observation dates and values, plus trend stats.

MCP Server Mode

Claude Desktop (claude_desktop_config.json):

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

Then ask Claude:

• "What's the current unemployment rate and how has it trended over the past 2 years?"
• "Is the yield curve still inverted? What's the current spread?"
• "Compare inflation (CPI, core CPI, PCE) over the last 24 months."
• "What's the Fed funds rate trajectory since the hiking cycle started in 2022?"

---

MCP Tools Exposed

get_economic_indicator

Fetch time-series data for a single named indicator with full observations and trend stats.

Arguments:

Field	Type	Required	Description
indicator	string	Yes	Indicator name from the catalog
periods	integer	No	Number of observations (default 24, max 500)

Returns: series_id, name, description, units, frequency, category, latest_value, latest_date, change stats, full observations array

Example:

{
  "name": "get_economic_indicator",
  "arguments": {"indicator": "yield_curve", "periods": 60}
}

---

list_indicators

Return the full catalog of 30+ available indicators. No arguments required.

Returns: Array of objects with indicator_name, series_id, name, description, units, frequency, category

Example:

{"name": "list_indicators", "arguments": {}}

---

compare_indicators

Fetch multiple indicators simultaneously. Returns summary stats for each (no full observations array — use get_economic_indicator for full data on individual series).

Arguments:

Field	Type	Required	Description
indicators	array	No	List of indicator names (empty = default 5-indicator dashboard)
periods	integer	No	Observations per indicator (default 24)

Example:

{
  "name": "compare_indicators",
  "arguments": {
    "indicators": ["sp500", "vix", "treasury_10y", "yield_curve"],
    "periods": 30
  }
}

---

get_indicator_by_series_id

Fetch any FRED series by its raw series ID. Unlocks the full 800,000+ FRED catalog.

Arguments:

Field	Type	Required	Description
series_id	string	Yes	FRED series ID (e.g. 'SOFR', 'WALCL', 'DFII10')
periods	integer	No	Number of observations (default 24)

Example:

{
  "name": "get_indicator_by_series_id",
  "arguments": {"series_id": "SOFR", "periods": 90}
}

---

Input Schema

Field	Type	Default	Description
indicators	array	[]	List of named indicators (empty = default dashboard)
periods	integer	24	Observations per indicator (max 500)
seriesId	string	""	Raw FRED series ID (overrides indicators if set)
serveMcp	boolean	false	Start MCP server instead of batch run

---

Use Case Recipes

Recipe 1: Recession Signal Monitor

Check the three classic recession precursors simultaneously:

{
  "indicators": ["yield_curve", "initial_claims", "gdp_growth"],
  "periods": 36
}

• Yield curve negative = inverted (recession historically follows in 6–18 months)
• Initial claims rising = labor market weakening
• GDP growth decelerating toward negative = possible contraction

In MCP mode: Ask Claude: "Based on current FRED data, how many recession signals are currently active?"

---

Recipe 2: Inflation Dashboard (Fed's Framework)

Compare the three inflation measures the Fed monitors:

{
  "indicators": ["cpi", "core_cpi", "pce_inflation"],
  "periods": 36
}

PCE is the Fed's official target (2%). Core CPI leads PCE directionally. Compare all three to understand where inflation is heading and whether the Fed's target is in range.

---

Recipe 3: Housing Market Analysis

Complete housing sector picture:

{
  "indicators": ["housing_starts", "existing_home_sales", "home_price_index", "mortgage_30y"],
  "periods": 24
}

Mortgage rate versus starts versus prices tells you whether the market is supply-constrained, demand-constrained, or in a rate lock-in trap.

---

Recipe 4: Fed Policy Context

Full rate environment picture:

{
  "indicators": ["fed_funds_rate", "treasury_2y", "treasury_10y", "yield_curve", "mortgage_30y"],
  "periods": 48
}

Shows the Fed's policy rate, how the market is pricing future rates (2Y), the long end (10Y), the resulting spread, and the passthrough to consumer borrowing costs.

---

Recipe 5: Market Stress Indicators

Risk-on / risk-off dashboard:

{
  "indicators": ["sp500", "vix", "dollar_index", "treasury_10y"],
  "periods": 60
}

High VIX + falling S&P + rising dollar + falling 10Y = risk-off flight to safety. Useful for macro regime identification.

---

Recipe 6: Labor Market Deep Dive

Full labor market picture beyond just the headline unemployment rate:

{
  "indicators": ["unemployment", "payrolls", "initial_claims", "jolts_openings", "participation_rate"],
  "periods": 36
}

JOLTS openings / payrolls ratio = labor market tightness. Initial claims trending up = leading indicator of weakness before it shows in headline unemployment.

---

Recipe 7: Custom FRED Series — Fed Balance Sheet

Track the Fed's balance sheet (quantitative tightening progress):

{"seriesId": "WALCL", "periods": 100}

Or compare real yields to nominal:

{"seriesId": "DFII10", "periods": 60}

DFII10 = 10-year TIPS yield (real yield) — subtract from DGS10 (nominal 10Y) to get implied 10Y inflation breakeven.

---

Connecting to Claude Desktop / Claude Code

macOS Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Windows Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json): Same JSON structure as above.

Claude Code (project .claude/settings.json):

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

Direct HTTP (any MCP client):

• GET http://<run-url>:4321/mcp/tools — list available tools
• POST http://<run-url>:4321/mcp/call with body {"name": "get_economic_indicator", "arguments": {"indicator": "unemployment", "periods": 24}}

---

Technical Architecture

No API key required: FRED data is fetched via https://fred.stlouisfed.org/graph/fredgraph.csv?id=SERIES_ID — the public graph export endpoint used by the FRED website's own charts. It returns a two-column CSV (DATE, VALUE) for the full history of any series. No registration, no API key, no rate limits.

Trend computation: After fetching, the actor computes:

• latest_value / latest_date — most recent non-null observation
• change_from_previous — absolute change from the prior period
• change_pct_from_previous — percentage change from prior period
• change_pct_yoy — year-over-year percentage change (period -13 for monthly)
• period_min / period_max / period_avg — statistics for the requested window

Concurrent fetching: compare_indicators uses asyncio.gather() to fetch all series in parallel — a 5-indicator comparison completes in the time of a single HTTP request (fastest single series).

Batch vs MCP mode:

• Batch: runs once, pushes structured summary records to Apify dataset, full observation arrays stored in key-value store
• MCP server: starts HTTP server on port 4321, serves all 4 tools indefinitely, fetches live data on each tool call

---

Available Indicators Reference

Name	Series ID	Description	Freq
unemployment	UNRATE	Unemployment Rate	Monthly
payrolls	PAYEMS	Total Nonfarm Payrolls	Monthly
initial_claims	ICSA	Initial Jobless Claims	Weekly
jolts_openings	JTSJOL	Job Openings (JOLTS)	Monthly
participation_rate	CIVPART	Labor Force Participation Rate	Monthly
cpi	CPIAUCSL	CPI — All Urban Consumers	Monthly
core_cpi	CPILFESL	Core CPI (ex Food & Energy)	Monthly
pce_inflation	PCEPI	PCE Price Index	Monthly
ppi	PPIACO	Producer Price Index	Monthly
gdp	GDP	Nominal GDP	Quarterly
real_gdp	GDPC1	Real GDP (Chained 2017 $)	Quarterly
gdp_growth	A191RL1Q225SBEA	Real GDP Growth Rate	Quarterly
industrial_production	INDPRO	Industrial Production Index	Monthly
capacity_utilization	TCU	Capacity Utilization — Total Industry	Monthly
fed_funds_rate	DFF	Federal Funds Effective Rate	Daily
treasury_10y	DGS10	10-Year Treasury Rate	Daily
treasury_2y	DGS2	2-Year Treasury Rate	Daily
treasury_3m	DGS3MO	3-Month Treasury Rate	Daily
yield_curve	T10Y2Y	10Y-2Y Treasury Yield Spread	Daily
mortgage_30y	MORTGAGE30US	30-Year Fixed Mortgage Rate	Weekly
housing_starts	HOUST	Housing Starts	Monthly
home_price_index	CSUSHPISA	Case-Shiller Home Price Index	Monthly
existing_home_sales	EXHOSLUSM495S	Existing Home Sales	Monthly
retail_sales	RSAFS	Retail & Food Services Sales	Monthly
pce	PCE	Personal Consumption Expenditures	Monthly
consumer_confidence	UMCSENT	UMich Consumer Sentiment	Monthly
m2_money_supply	M2SL	M2 Money Supply	Monthly
credit_card_rate	TERMCBCCALLNS	Credit Card Interest Rate	Quarterly
trade_balance	BOPGSTB	US Trade Balance	Monthly
dollar_index	DTWEXBGS	USD Trade-Weighted Index	Weekly
sp500	SP500	S&P 500 Index	Daily
vix	VIXCLS	CBOE VIX	Daily

---

Pricing

Volume	Price
First 1,000 results	$0.30
1,001 – 50,000 results	$0.20/1k
MCP server (per session-hour)	Metered by result count

ROI context: Bloomberg terminal = $24,000/year. Refinitiv Eikon = $18,000/year. This actor delivers the core macro time-series data from those platforms — the unemployment rate, CPI, fed funds rate, yield curve, housing starts — from the same authoritative source (FRED), via a natural language interface, at a fraction of the cost.

---

Data Source Notes

• Source: St. Louis Federal Reserve FRED — https://fred.stlouisfed.org/
• Endpoint used: https://fred.stlouisfed.org/graph/fredgraph.csv?id={SERIES_ID} — public, no auth required
• Data authority: FRED aggregates data from the BLS, BEA, Census Bureau, Federal Reserve Board, Freddie Mac, and many other official sources
• Update frequency: FRED updates each series on a different schedule — typically same-day for daily series (Treasury yields, fed funds), same-week for weekly, and 1–2 days after publication for monthly
• Historical depth: Varies by series. Unemployment rate goes to 1948. 10Y Treasury to 1962. GDP to 1947. S&P 500 to 1927.
• Missing values: FRED reports missing values as . — the actor skips these and only returns numeric observations

---

Support

• Issues: File a GitHub issue on the actor repository
• Apify Community: community.apify.com
• FRED data browser: fred.stlouisfed.org
• FRED API docs: fred.stlouisfed.org/docs/api/fred/
• Series search: Use the FRED website to find series IDs for the get_indicator_by_series_id tool