Basic Usage Examples

Learn how to use the FRED MCP Server with practical examples covering the most common economic data queries.

Getting Started

Before diving into examples, ensure you have:

Configured your FRED API key
Connected the server to your MCP client
Verified the connection is working

Common Economic Queries

Unemployment Rate

Current Rate
Last Year
Historical Trend

Query: “What’s the current US unemployment rate?”

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "UNRATE",
    "limit": 1,
    "sort_order": "desc"
  }
}

Response: Latest unemployment rate value

Query: “Show unemployment rate for the last 12 months”

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "UNRATE",
    "limit": 12,
    "sort_order": "desc"
  }
}

Response: Monthly unemployment values

Query: “Get unemployment trend since 2020”

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "UNRATE",
    "observation_start": "2020-01-01"
  }
}

Response: Full pandemic-era unemployment data

Inflation Tracking

Current Inflation
Core vs Headline
Monthly Changes

Query: “What’s the current inflation rate?”

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "CPIAUCSL",
    "units": "pc1",
    "limit": 1,
    "sort_order": "desc"
  }
}

Response: Year-over-year CPI change

Query: “Compare core and headline inflation”

// Headline CPI
{
  "tool": "fred_get_series",
  "params": {
    "series_id": "CPIAUCSL",
    "units": "pc1",
    "limit": 12
  }
}

// Core CPI
{
  "tool": "fred_get_series",
  "params": {
    "series_id": "CPILFESL",
    "units": "pc1",
    "limit": 12
  }
}

Query: “Show month-to-month inflation changes”

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "CPIAUCSL",
    "units": "pch",
    "limit": 12
  }
}

Response: Monthly percent changes

GDP and Growth

Latest GDP
Real GDP Growth
GDP Components

Query: “What’s the latest GDP figure?”

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "GDP",
    "limit": 1,
    "sort_order": "desc"
  }
}

Response: Nominal GDP in billions

Query: “Show real GDP growth rate”

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "GDPC1",
    "units": "pca",
    "limit": 8
  }
}

Response: Annualized growth rates

Query: “Break down GDP by components”

// Personal Consumption
{
  "series_id": "PCE",
  "limit": 4
}

// Investment
{
  "series_id": "GPDI",
  "limit": 4
}

// Government
{
  "series_id": "GCE",
  "limit": 4
}

// Net Exports
{
  "series_id": "NETEXP",
  "limit": 4
}

Interest Rates

Federal Reserve Rates

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "DFF",
    "limit": 30
  }
}

// Upper bound
{
  "tool": "fred_get_series",
  "params": {
    "series_id": "DFEDTARU",
    "limit": 12
  }
}

// Lower bound
{
  "tool": "fred_get_series",
  "params": {
    "series_id": "DFEDTARL",
    "limit": 12
  }
}

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "REAINTRATREARAT10Y",
    "limit": 12
  }
}

Treasury Yields

// 3-Month
{"series_id": "DGS3MO", "limit": 1}

// 2-Year
{"series_id": "DGS2", "limit": 1}

// 5-Year
{"series_id": "DGS5", "limit": 1}

// 10-Year
{"series_id": "DGS10", "limit": 1}

// 30-Year
{"series_id": "DGS30", "limit": 1}

// 10Y-2Y Spread (Recession Indicator)
{
  "tool": "fred_get_series",
  "params": {
    "series_id": "T10Y2Y",
    "limit": 252
  }
}

Labor Market Data

Employment Statistics

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "PAYEMS",
    "units": "chg",
    "limit": 12
  }
}

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "CIVPART",
    "limit": 24
  }
}

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "CES0500000003",
    "units": "pc1",
    "limit": 12
  }
}

Jobless Claims

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "ICSA",
    "limit": 52
  }
}

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "CCSA",
    "limit": 52
  }
}

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "IC4WSA",
    "limit": 52
  }
}

Housing Market

Home Prices and Sales

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "CSUSHPISA",
    "units": "pc1",
    "limit": 24
  }
}

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "HSN1F",
    "limit": 12
  }
}

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "HOUST",
    "limit": 12
  }
}

Mortgage Rates

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "MORTGAGE30US",
    "limit": 52
  }
}

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "MORTGAGE15US",
    "limit": 52
  }
}

Financial Markets

Stock Market Indices

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "SP500",
    "limit": 252
  }
}

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "NASDAQCOM",
    "limit": 252
  }
}

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "VIXCLS",
    "limit": 252
  }
}

Exchange Rates

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "DEXUSEU",
    "limit": 30
  }
}

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "DEXJPUS",
    "limit": 30
  }
}

{
  "tool": "fred_get_series",
  "params": {
    "series_id": "DTWEXBGS",
    "limit": 52
  }
}

Discovering Data

Search for Series

{
  "tool": "fred_search",
  "params": {
    "search_text": "inflation",
    "tag_names": "usa,monthly",
    "limit": 10
  }
}

{
  "tool": "fred_search",
  "params": {
    "search_text": "unemployment",
    "tag_names": "state,monthly,sa",
    "limit": 20
  }
}

{
  "tool": "fred_search",
  "params": {
    "search_text": "recession",
    "order_by": "popularity",
    "limit": 10
  }
}

Browse Categories

{
  "tool": "fred_browse",
  "params": {
    "browse_type": "categories"
  }
}

{
  "tool": "fred_browse",
  "params": {
    "browse_type": "category_series",
    "category_id": 22,
    "order_by": "popularity",
    "limit": 20
  }
}

{
  "tool": "fred_browse",
  "params": {
    "browse_type": "releases",
    "order_by": "name",
    "limit": 30
  }
}

Creating Reports

Economic Dashboard

// Comprehensive economic snapshot
async function getEconomicDashboard() {
  const indicators = [
    { id: "GDPC1", name: "Real GDP", transform: "pca" },
    { id: "UNRATE", name: "Unemployment" },
    { id: "CPIAUCSL", name: "CPI Inflation", transform: "pc1" },
    { id: "DFF", name: "Fed Funds Rate" },
    { id: "DGS10", name: "10-Year Treasury" },
    { id: "SP500", name: "S&P 500" }
  ];

  const results = {};
  for (const indicator of indicators) {
    const params = {
      series_id: indicator.id,
      limit: 1,
      sort_order: "desc"
    };
    if (indicator.transform) {
      params.units = indicator.transform;
    }
    results[indicator.name] = await callTool("fred_get_series", params);
  }
  return results;
}

Comparative Analysis

// Compare periods
async function comparePeriods(seriesId, period1Start, period2Start) {
  const period1 = await callTool("fred_get_series", {
    series_id: seriesId,
    observation_start: period1Start,
    observation_end: addYear(period1Start),
    units: "pc1"
  });

  const period2 = await callTool("fred_get_series", {
    series_id: seriesId,
    observation_start: period2Start,
    observation_end: addYear(period2Start),
    units: "pc1"
  });

  return { period1, period2 };
}

Tips for Effective Queries

Start Simple

Begin with basic queries and add complexity as needed

Use Transformations

Apply units transformations for meaningful comparisons

Check Frequency

Ensure data frequencies match when comparing series

Handle Missing Data

Some series have gaps; always check for null values

Optimize Requests

Request only the data you need using limits and date ranges

Common Patterns

Latest Value Pattern

{
  "series_id": "SERIES_ID",
  "limit": 1,
  "sort_order": "desc"
}

Time Period Pattern

{
  "series_id": "SERIES_ID",
  "observation_start": "START_DATE",
  "observation_end": "END_DATE"
}

Growth Rate Pattern

{
  "series_id": "SERIES_ID",
  "units": "pc1",  // or "pch", "pca"
  "limit": 12
}

Frequency Conversion Pattern

{
  "series_id": "SERIES_ID",
  "frequency": "m",  // or "q", "a"
  "aggregation_method": "avg"
}

Next Steps

Economic Indicators

Deep dive into key indicators

Time Series Analysis

Advanced analysis techniques

Data Transformations

Master data transformations

Advanced Queries

Complex query patterns

​Basic Usage Examples

​Getting Started

​Common Economic Queries

​Unemployment Rate

​Inflation Tracking

​GDP and Growth

​Interest Rates

​Federal Reserve Rates

​Treasury Yields

​Labor Market Data

​Employment Statistics

​Jobless Claims

​Housing Market

​Home Prices and Sales

​Mortgage Rates

​Financial Markets

​Stock Market Indices

​Exchange Rates

​Discovering Data

​Search for Series

​Browse Categories

​Creating Reports

​Economic Dashboard

​Comparative Analysis

​Tips for Effective Queries

​Common Patterns

​Latest Value Pattern

​Time Period Pattern

​Growth Rate Pattern

​Frequency Conversion Pattern

​Next Steps