# fred_browse
Source: https://fred-mcp-server.amorelli.tech/api-reference/fred-browse

Navigate FRED's complete catalog through categories, releases, and sources

# fred\_browse

Browse and navigate through FRED's hierarchical catalog structure to discover available economic data series.

## Overview

The `fred_browse` tool provides systematic navigation through FRED's extensive catalog of over 800,000 economic time series. Use it to:

* Explore economic categories and subcategories
* Browse data releases from various sources
* List all series within a specific category or release
* Discover data sources and their available series

## Parameters

<ParamField type="string">
  Type of browsing operation to perform.

  **Options:**

  * `categories`: Browse category tree
  * `releases`: List data releases
  * `sources`: List data sources
  * `category_series`: Get all series in a category
  * `release_series`: Get all series in a release
</ParamField>

<ParamField type="number">
  Category ID for browsing subcategories or series.

  **Required when:**

  * `browse_type` is `category_series`

  **Optional when:**

  * `browse_type` is `categories` (omit to get root categories)

  **Common IDs:**

  * `32991`: Money, Banking & Finance
  * `10`: Population, Employment & Labor Markets
  * `1`: Production & Business Activity
  * `32992`: Prices
  * `3008`: U.S. Regional Data
  * `32264`: International Data
</ParamField>

<ParamField type="number">
  Release ID for browsing series within a release.

  **Required when:**

  * `browse_type` is `release_series`

  **Popular Release IDs:**

  * `53`: GDP
  * `50`: Employment Situation
  * `10`: Consumer Price Index
  * `15`: Industrial Production and Capacity Utilization
  * `18`: Federal Reserve Economic Data
</ParamField>

<ParamField type="number">
  Maximum number of results to return (1-1000).
</ParamField>

<ParamField type="number">
  Number of results to skip for pagination.
</ParamField>

<ParamField type="string">
  Field to order results by.

  **Options vary by browse\_type:**

  * Categories: `name`, `series_count`
  * Series: `series_id`, `title`, `popularity`, `last_updated`
  * Releases: `name`, `release_id`, `press_release`
</ParamField>

<ParamField type="string">
  Sort order for results.

  **Options:**

  * `asc`: Ascending order
  * `desc`: Descending order
</ParamField>

## Examples

### Browse Root Categories

<CodeGroup>
  ```json Request theme={null}
  {
    "tool": "fred_browse",
    "params": {
      "browse_type": "categories"
    }
  }
  ```

  ```json Response theme={null}
  {
    "categories": [
      {
        "id": 32991,
        "name": "Money, Banking, & Finance",
        "parent_id": 0,
        "series_count": 48000
      },
      {
        "id": 10,
        "name": "Population, Employment, & Labor Markets",
        "parent_id": 0,
        "series_count": 84000
      },
      {
        "id": 1,
        "name": "Production & Business Activity",
        "parent_id": 0,
        "series_count": 52000
      }
    ],
    "metadata": {
      "count": 8,
      "total": 8
    }
  }
  ```
</CodeGroup>

### Browse Subcategories

<CodeGroup>
  ```json Request theme={null}
  {
    "tool": "fred_browse",
    "params": {
      "browse_type": "categories",
      "category_id": 32991
    }
  }
  ```

  ```json Response theme={null}
  {
    "categories": [
      {
        "id": 22,
        "name": "Interest Rates",
        "parent_id": 32991,
        "series_count": 12000
      },
      {
        "id": 24,
        "name": "Exchange Rates",
        "parent_id": 32991,
        "series_count": 3500
      },
      {
        "id": 46,
        "name": "Banking",
        "parent_id": 32991,
        "series_count": 8000
      }
    ]
  }
  ```
</CodeGroup>

### Get Series in a Category

<CodeGroup>
  ```json Request theme={null}
  {
    "tool": "fred_browse",
    "params": {
      "browse_type": "category_series",
      "category_id": 22,
      "limit": 5,
      "order_by": "popularity",
      "sort_order": "desc"
    }
  }
  ```

  ```json Response theme={null}
  {
    "series": [
      {
        "id": "DGS10",
        "title": "Market Yield on U.S. Treasury Securities at 10-Year Constant Maturity",
        "observation_start": "1962-01-02",
        "observation_end": "2024-12-31",
        "frequency": "Daily",
        "units": "Percent",
        "seasonal_adjustment": "Not Seasonally Adjusted",
        "popularity": 95
      },
      {
        "id": "DFF",
        "title": "Federal Funds Effective Rate",
        "observation_start": "1954-07-01",
        "observation_end": "2024-12-31",
        "frequency": "Daily",
        "units": "Percent",
        "seasonal_adjustment": "Not Seasonally Adjusted",
        "popularity": 93
      }
    ],
    "metadata": {
      "count": 5,
      "offset": 0,
      "limit": 5,
      "total": 12000
    }
  }
  ```
</CodeGroup>

### Browse Data Releases

<CodeGroup>
  ```json Request theme={null}
  {
    "tool": "fred_browse",
    "params": {
      "browse_type": "releases",
      "limit": 10,
      "order_by": "name"
    }
  }
  ```

  ```json Response theme={null}
  {
    "releases": [
      {
        "id": 10,
        "name": "Consumer Price Index",
        "press_release": true,
        "link": "https://www.bls.gov/news.release/cpi.nr0.htm",
        "source": "U.S. Bureau of Labor Statistics"
      },
      {
        "id": 50,
        "name": "Employment Situation",
        "press_release": true,
        "link": "https://www.bls.gov/news.release/empsit.nr0.htm",
        "source": "U.S. Bureau of Labor Statistics"
      },
      {
        "id": 53,
        "name": "Gross Domestic Product",
        "press_release": true,
        "link": "https://www.bea.gov/news/current-releases",
        "source": "U.S. Bureau of Economic Analysis"
      }
    ],
    "metadata": {
      "count": 10,
      "total": 300
    }
  }
  ```
</CodeGroup>

### Browse Data Sources

<CodeGroup>
  ```json Request theme={null}
  {
    "tool": "fred_browse",
    "params": {
      "browse_type": "sources",
      "limit": 5
    }
  }
  ```

  ```json Response theme={null}
  {
    "sources": [
      {
        "id": 1,
        "name": "Board of Governors of the Federal Reserve System (US)",
        "link": "https://www.federalreserve.gov/",
        "series_count": 45000
      },
      {
        "id": 2,
        "name": "U.S. Bureau of Labor Statistics",
        "link": "https://www.bls.gov/",
        "series_count": 75000
      },
      {
        "id": 3,
        "name": "U.S. Bureau of Economic Analysis",
        "link": "https://www.bea.gov/",
        "series_count": 35000
      }
    ],
    "metadata": {
      "count": 5,
      "total": 89
    }
  }
  ```
</CodeGroup>

## Navigation Strategies

### Hierarchical Exploration

<Steps>
  <Step title="Start with Root Categories">
    ```json theme={null}
    {
      "browse_type": "categories"
    }
    ```
  </Step>

  <Step title="Drill Down to Subcategories">
    ```json theme={null}
    {
      "browse_type": "categories",
      "category_id": 32991
    }
    ```
  </Step>

  <Step title="List Series in Category">
    ```json theme={null}
    {
      "browse_type": "category_series",
      "category_id": 22,
      "order_by": "popularity"
    }
    ```
  </Step>

  <Step title="Retrieve Specific Series">
    Use `fred_get_series` with the discovered series ID
  </Step>
</Steps>

### Release-Based Discovery

<Steps>
  <Step title="List All Releases">
    ```json theme={null}
    {
      "browse_type": "releases",
      "order_by": "name"
    }
    ```
  </Step>

  <Step title="Get Series in Release">
    ```json theme={null}
    {
      "browse_type": "release_series",
      "release_id": 10
    }
    ```
  </Step>

  <Step title="Filter and Retrieve">
    Use series IDs with `fred_get_series`
  </Step>
</Steps>

## Common Use Cases

### Finding Interest Rate Data

```json theme={null}
// Step 1: Navigate to Money & Banking
{
  "browse_type": "categories",
  "category_id": 32991
}

// Step 2: Find Interest Rates category (ID: 22)
{
  "browse_type": "category_series",
  "category_id": 22,
  "order_by": "popularity",
  "limit": 20
}
```

### Exploring Regional Data

```json theme={null}
// Step 1: Go to U.S. Regional Data
{
  "browse_type": "categories",
  "category_id": 3008
}

// Step 2: Browse states
{
  "browse_type": "categories",
  "category_id": 27281  // States category
}

// Step 3: Get California data
{
  "browse_type": "category_series",
  "category_id": 27286  // California
}
```

### Finding Latest Economic Releases

```json theme={null}
// Get recent releases
{
  "browse_type": "releases",
  "order_by": "release_id",
  "sort_order": "desc",
  "limit": 10
}
```

## Category Reference

### Top-Level Categories

| ID    | Name                                   | Description                                       | Series Count |
| ----- | -------------------------------------- | ------------------------------------------------- | ------------ |
| 32991 | Money, Banking & Finance               | Financial markets, interest rates, exchange rates | \~48,000     |
| 10    | Population, Employment & Labor Markets | Jobs, unemployment, demographics                  | \~84,000     |
| 1     | Production & Business Activity         | GDP, industrial production, business indicators   | \~52,000     |
| 32992 | Prices                                 | Inflation, CPI, PPI, commodity prices             | \~32,000     |
| 3008  | U.S. Regional Data                     | State and metro area statistics                   | \~350,000    |
| 32264 | International Data                     | Global economic indicators                        | \~150,000    |
| 32263 | Academic Data                          | Research datasets from universities               | \~15,000     |

### Popular Subcategories

| Parent | ID | Name                   | Key Series                |
| ------ | -- | ---------------------- | ------------------------- |
| 32991  | 22 | Interest Rates         | DFF, DGS10, DGS2, TB3MS   |
| 32991  | 24 | Exchange Rates         | DEXUSEU, DEXJPUS, DEXCHUS |
| 10     | 12 | Unemployment Rate      | UNRATE, U6RATE, CIVPART   |
| 1      | 18 | GDP                    | GDP, GDPC1, GDPPOT        |
| 32992  | 9  | Consumer Price Indexes | CPIAUCSL, CPILFESL        |

## Error Handling

### Common Errors

| Error                  | Cause                      | Solution                                                                     |
| ---------------------- | -------------------------- | ---------------------------------------------------------------------------- |
| `Invalid browse_type`  | Unknown browse\_type value | Use one of: categories, releases, sources, category\_series, release\_series |
| `category_id required` | Missing required parameter | Provide category\_id when browse\_type is category\_series                   |
| `release_id required`  | Missing required parameter | Provide release\_id when browse\_type is release\_series                     |
| `Invalid category_id`  | Category doesn't exist     | Verify category\_id or browse to find correct ID                             |

### Best Practices

<Info>
  **Tips for Efficient Browsing:**

  * Start broad and narrow down systematically
  * Use popularity ordering to find commonly-used series
  * Plan navigation path to minimize API calls
  * Combine with `fred_search` for targeted discovery
</Info>

## Related Tools

<CardGroup>
  <Card title="fred_search" icon="magnifying-glass" href="/api-reference/fred-search">
    Search for specific series by keywords
  </Card>

  <Card title="fred_get_series" icon="chart-line" href="/api-reference/fred-get-series">
    Retrieve data for discovered series
  </Card>
</CardGroup>


# fred_get_series
Source: https://fred-mcp-server.amorelli.tech/api-reference/fred-get-series

Retrieve time series data with transformations and aggregations

# fred\_get\_series

Retrieve any FRED time series data by ID with support for data transformations, frequency changes, and custom date ranges.

## Overview

The `fred_get_series` tool is your primary interface for accessing actual economic data. It supports:

* Retrieving observations for any of the 800,000+ series
* Applying mathematical transformations (growth rates, percent changes)
* Converting between frequencies (daily to monthly, monthly to quarterly)
* Custom date ranges and vintage data
* Multiple aggregation methods

## Parameters

<ParamField type="string">
  The FRED series ID to retrieve data for.

  **Popular IDs:**

  * `GDP`: Gross Domestic Product
  * `UNRATE`: Unemployment Rate
  * `CPIAUCSL`: Consumer Price Index
  * `DFF`: Federal Funds Rate
  * `SP500`: S\&P 500 Index

  **Finding IDs:**
  Use `fred_search` or `fred_browse` to discover series IDs
</ParamField>

<ParamField type="string">
  Start date for observations in YYYY-MM-DD format.

  **Examples:**

  * `2024-01-01`: Start of 2024
  * `2020-03-01`: Beginning of pandemic period
  * `2008-09-01`: Start of financial crisis

  **Default:** Series start date
</ParamField>

<ParamField type="string">
  End date for observations in YYYY-MM-DD format.

  **Examples:**

  * `2024-12-31`: End of 2024
  * `2023-12-31`: Full year 2023

  **Default:** Most recent available data
</ParamField>

<ParamField type="number">
  Maximum number of observations to return (1-100000).

  **Usage:**

  * Small limits for recent data: `12` for last year of monthly data
  * Large limits for historical analysis
</ParamField>

<ParamField type="number">
  Number of observations to skip from the beginning.
</ParamField>

<ParamField type="string">
  Sort order of observations by date.

  **Options:**

  * `asc`: Chronological order (oldest first)
  * `desc`: Reverse chronological (newest first)
</ParamField>

<ParamField type="string">
  Data transformation to apply.

  **Options:**

  * `lin`: Levels (no transformation) - raw values
  * `chg`: Change from previous period
  * `ch1`: Change from year ago
  * `pch`: Percent change from previous period
  * `pc1`: Percent change from year ago
  * `pca`: Compounded annual rate of change
  * `cch`: Continuously compounded rate of change
  * `cca`: Continuously compounded annual rate
  * `log`: Natural logarithm

  **Common uses:**

  * `pc1` for year-over-year inflation
  * `pch` for month-over-month growth
  * `log` for regression analysis
</ParamField>

<ParamField type="string">
  Frequency aggregation/conversion.

  **Main options:**

  * `d`: Daily
  * `w`: Weekly
  * `bw`: Biweekly
  * `m`: Monthly
  * `q`: Quarterly
  * `sa`: Semiannual
  * `a`: Annual

  **Weekly variants:**

  * `wef`: Week Ending Friday
  * `weth`: Week Ending Thursday
  * `wew`: Week Ending Wednesday
  * `wetu`: Week Ending Tuesday
  * `wem`: Week Ending Monday
  * `wesu`: Week Ending Sunday
  * `wesa`: Week Ending Saturday

  **Default:** Native series frequency
</ParamField>

<ParamField type="string">
  Method for aggregating to lower frequencies.

  **Options:**

  * `avg`: Average over period
  * `sum`: Sum of values in period
  * `eop`: End of period value

  **Usage examples:**

  * `avg` for interest rates, prices
  * `sum` for flows like GDP, sales
  * `eop` for stock prices, levels
</ParamField>

<ParamField type="number">
  Output format type.

  **Options:**

  * `1`: Time series observations
  * `2`: Observations by vintage date
  * `3`: Observations by release date
  * `4`: Initial release only

  **Note:** Types 2-4 for vintage analysis
</ParamField>

<ParamField type="string">
  Specific vintage date(s) in YYYY-MM-DD format.

  **Usage:**

  * Single date: `2024-01-01`
  * Date range: `2024-01-01:2024-12-31`

  **Purpose:** Retrieve data as it existed on specific dates
</ParamField>

## Examples

### Basic Series Retrieval

<CodeGroup>
  ```json Request theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "UNRATE",
      "limit": 12
    }
  }
  ```

  ```json Response theme={null}
  {
    "series": {
      "id": "UNRATE",
      "title": "Unemployment Rate",
      "units": "Percent",
      "frequency": "Monthly",
      "seasonal_adjustment": "Seasonally Adjusted"
    },
    "observations": [
      {"date": "2024-01-01", "value": 3.7},
      {"date": "2024-02-01", "value": 3.9},
      {"date": "2024-03-01", "value": 3.8},
      {"date": "2024-04-01", "value": 3.9},
      {"date": "2024-05-01", "value": 4.0},
      {"date": "2024-06-01", "value": 4.0},
      {"date": "2024-07-01", "value": 4.3},
      {"date": "2024-08-01", "value": 4.2},
      {"date": "2024-09-01", "value": 4.1},
      {"date": "2024-10-01", "value": 4.1},
      {"date": "2024-11-01", "value": 4.2},
      {"date": "2024-12-01", "value": 4.2}
    ],
    "metadata": {
      "count": 12,
      "observation_start": "2024-01-01",
      "observation_end": "2024-12-01"
    }
  }
  ```
</CodeGroup>

### Year-over-Year Inflation

<CodeGroup>
  ```json Request theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "CPIAUCSL",
      "units": "pc1",
      "observation_start": "2024-01-01",
      "limit": 12
    }
  }
  ```

  ```json Response theme={null}
  {
    "series": {
      "id": "CPIAUCSL",
      "title": "Consumer Price Index for All Urban Consumers",
      "units": "Percent Change from Year Ago",
      "transformation": "pc1"
    },
    "observations": [
      {"date": "2024-01-01", "value": 3.1},
      {"date": "2024-02-01", "value": 3.2},
      {"date": "2024-03-01", "value": 3.5},
      {"date": "2024-04-01", "value": 3.4},
      {"date": "2024-05-01", "value": 3.3},
      {"date": "2024-06-01", "value": 3.0},
      {"date": "2024-07-01", "value": 2.9},
      {"date": "2024-08-01", "value": 2.5},
      {"date": "2024-09-01", "value": 2.4},
      {"date": "2024-10-01", "value": 2.6},
      {"date": "2024-11-01", "value": 2.7},
      {"date": "2024-12-01", "value": 2.9}
    ]
  }
  ```
</CodeGroup>

### Quarterly GDP Growth

<CodeGroup>
  ```json Request theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "GDPC1",
      "units": "pca",
      "observation_start": "2023-01-01",
      "observation_end": "2024-12-31"
    }
  }
  ```

  ```json Response theme={null}
  {
    "series": {
      "id": "GDPC1",
      "title": "Real Gross Domestic Product",
      "units": "Compounded Annual Rate of Change",
      "frequency": "Quarterly"
    },
    "observations": [
      {"date": "2023-01-01", "value": 2.2},
      {"date": "2023-04-01", "value": 2.1},
      {"date": "2023-07-01", "value": 4.9},
      {"date": "2023-10-01", "value": 3.4},
      {"date": "2024-01-01", "value": 1.6},
      {"date": "2024-04-01", "value": 3.0},
      {"date": "2024-07-01", "value": 2.8},
      {"date": "2024-10-01", "value": 2.5}
    ]
  }
  ```
</CodeGroup>

### Convert Daily to Monthly

<CodeGroup>
  ```json Request theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "DFF",
      "frequency": "m",
      "aggregation_method": "avg",
      "observation_start": "2024-01-01",
      "limit": 12
    }
  }
  ```

  ```json Response theme={null}
  {
    "series": {
      "id": "DFF",
      "title": "Federal Funds Effective Rate",
      "original_frequency": "Daily",
      "requested_frequency": "Monthly",
      "aggregation": "Average"
    },
    "observations": [
      {"date": "2024-01-01", "value": 5.33},
      {"date": "2024-02-01", "value": 5.33},
      {"date": "2024-03-01", "value": 5.33},
      {"date": "2024-04-01", "value": 5.33},
      {"date": "2024-05-01", "value": 5.33},
      {"date": "2024-06-01", "value": 5.33},
      {"date": "2024-07-01", "value": 5.33},
      {"date": "2024-08-01", "value": 5.33},
      {"date": "2024-09-01", "value": 5.08},
      {"date": "2024-10-01", "value": 4.83},
      {"date": "2024-11-01", "value": 4.58},
      {"date": "2024-12-01", "value": 4.33}
    ]
  }
  ```
</CodeGroup>

## Common Use Cases

### Economic Dashboard

```json theme={null}
// GDP Growth (Quarterly)
{
  "series_id": "GDPC1",
  "units": "pca",
  "limit": 8
}

// Unemployment Rate (Monthly)
{
  "series_id": "UNRATE",
  "limit": 24
}

// Inflation Rate (Monthly YoY)
{
  "series_id": "CPIAUCSL",
  "units": "pc1",
  "limit": 24
}

// Federal Funds Rate (Daily)
{
  "series_id": "DFF",
  "limit": 30
}
```

### Historical Analysis

```json theme={null}
// Long-term GDP growth
{
  "series_id": "GDPC1",
  "units": "pc1",
  "observation_start": "1950-01-01",
  "frequency": "a"
}

// Unemployment during recessions
{
  "series_id": "UNRATE",
  "observation_start": "2007-01-01",
  "observation_end": "2010-12-31"
}

// Inflation in the 1970s
{
  "series_id": "CPIAUCSL",
  "units": "pc1",
  "observation_start": "1970-01-01",
  "observation_end": "1979-12-31"
}
```

### Financial Market Indicators

```json theme={null}
// 10-Year Treasury Yield
{
  "series_id": "DGS10",
  "limit": 252  // ~1 year of trading days
}

// Yield Curve (10Y-2Y Spread)
// Requires two calls and calculation
{
  "series_id": "T10Y2Y",
  "limit": 252
}

// S&P 500 Monthly Returns
{
  "series_id": "SP500",
  "units": "pch",
  "frequency": "m",
  "aggregation_method": "eop"
}
```

## Transformation Examples

### Growth Rate Calculations

<Tabs>
  <Tab title="Month-over-Month">
    ```json theme={null}
    {
      "series_id": "PAYEMS",
      "units": "chg",
      "limit": 12
    }
    ```

    Returns absolute change from previous month
  </Tab>

  <Tab title="Quarter-over-Quarter">
    ```json theme={null}
    {
      "series_id": "GDPC1",
      "units": "pch",
      "limit": 8
    }
    ```

    Returns percent change from previous quarter
  </Tab>

  <Tab title="Year-over-Year">
    ```json theme={null}
    {
      "series_id": "CPIAUCSL",
      "units": "pc1",
      "limit": 24
    }
    ```

    Returns percent change from same period last year
  </Tab>

  <Tab title="Annualized Rate">
    ```json theme={null}
    {
      "series_id": "GDPC1",
      "units": "pca",
      "limit": 8
    }
    ```

    Returns compounded annual rate of change
  </Tab>
</Tabs>

### Frequency Conversions

<Tabs>
  <Tab title="Daily to Monthly">
    ```json theme={null}
    {
      "series_id": "DFF",
      "frequency": "m",
      "aggregation_method": "avg"
    }
    ```

    Average daily values into monthly
  </Tab>

  <Tab title="Monthly to Quarterly">
    ```json theme={null}
    {
      "series_id": "CPIAUCSL",
      "frequency": "q",
      "aggregation_method": "avg"
    }
    ```

    Average monthly values into quarterly
  </Tab>

  <Tab title="Monthly to Annual">
    ```json theme={null}
    {
      "series_id": "UNRATE",
      "frequency": "a",
      "aggregation_method": "avg"
    }
    ```

    Average monthly values into annual
  </Tab>

  <Tab title="Daily to Weekly">
    ```json theme={null}
    {
      "series_id": "DEXUSEU",
      "frequency": "wef",
      "aggregation_method": "eop"
    }
    ```

    Week-ending Friday values
  </Tab>
</Tabs>

## Popular Series Reference

### Key Economic Indicators

| Series ID | Description       | Frequency | Common Transform |
| --------- | ----------------- | --------- | ---------------- |
| GDP       | Nominal GDP       | Quarterly | `units: "pch"`   |
| GDPC1     | Real GDP          | Quarterly | `units: "pca"`   |
| UNRATE    | Unemployment Rate | Monthly   | None (already %) |
| PAYEMS    | Nonfarm Payrolls  | Monthly   | `units: "chg"`   |
| CPIAUCSL  | CPI All Urban     | Monthly   | `units: "pc1"`   |
| CPILFESL  | Core CPI          | Monthly   | `units: "pc1"`   |
| PCEPI     | PCE Price Index   | Monthly   | `units: "pc1"`   |

### Interest Rates

| Series ID    | Description         | Frequency | Notes               |
| ------------ | ------------------- | --------- | ------------------- |
| DFF          | Fed Funds Effective | Daily     | Current policy rate |
| DGS10        | 10-Year Treasury    | Daily     | Long-term rate      |
| DGS2         | 2-Year Treasury     | Daily     | Short-term rate     |
| TB3MS        | 3-Month T-Bill      | Monthly   | Risk-free rate      |
| MORTGAGE30US | 30-Year Mortgage    | Weekly    | Consumer rate       |

### Market Indicators

| Series ID | Description      | Frequency | Transform for Returns |
| --------- | ---------------- | --------- | --------------------- |
| SP500     | S\&P 500 Index   | Daily     | `units: "pch"`        |
| DJIA      | Dow Jones        | Daily     | `units: "pch"`        |
| NASDAQCOM | NASDAQ Composite | Daily     | `units: "pch"`        |
| VIXCLS    | VIX Volatility   | Daily     | None                  |
| DEXUSEU   | EUR/USD Exchange | Daily     | `units: "pch"`        |

## Error Handling

### Common Errors

| Error                        | Cause                                | Solution                             |
| ---------------------------- | ------------------------------------ | ------------------------------------ |
| `Invalid series ID`          | Series doesn't exist                 | Use fred\_search to find correct ID  |
| `No data in range`           | Date range has no data               | Check series start/end dates         |
| `Invalid transformation`     | Transform not applicable             | Some transforms need positive values |
| `Frequency conversion error` | Can't convert to requested frequency | Check if conversion makes sense      |

### Validation Rules

<Warning>
  **Important constraints:**

  * Dates must be in YYYY-MM-DD format
  * observation\_start must be ≤ observation\_end
  * Some transformations require positive values
  * Not all frequency conversions are valid
</Warning>

## Best Practices

<Steps>
  <Step title="Know Your Data">
    Check series metadata (frequency, units, seasonal adjustment) before retrieval
  </Step>

  <Step title="Use Appropriate Transforms">
    Match transformation to analysis needs (growth rates for trends, logs for regression)
  </Step>

  <Step title="Consider Frequency">
    Align data frequencies when comparing multiple series
  </Step>

  <Step title="Handle Missing Data">
    Some series have gaps; check for null values in observations
  </Step>

  <Step title="Plan Queries Carefully">
    Think through data needs to minimize redundant requests
  </Step>
</Steps>

## Related Tools

<CardGroup>
  <Card title="fred_search" icon="magnifying-glass" href="/api-reference/fred-search">
    Find series IDs to retrieve
  </Card>

  <Card title="fred_browse" icon="folder-tree" href="/api-reference/fred-browse">
    Explore available categories
  </Card>
</CardGroup>


# fred_search
Source: https://fred-mcp-server.amorelli.tech/api-reference/fred-search

Search for FRED economic data series by keywords, tags, or filters

# fred\_search

Search across all 800,000+ FRED series using powerful text search, tag filtering, and attribute filters.

## Overview

The `fred_search` tool enables sophisticated searching across FRED's vast database. Use it to:

* Find series by keywords in titles and descriptions
* Filter by tags like "gdp", "monthly", "seasonally adjusted"
* Combine multiple search criteria
* Filter by frequency, units, or seasonal adjustment
* Sort by relevance, popularity, or recency

## Parameters

<ParamField type="string">
  Text to search for in series titles and descriptions.

  **Search tips:**

  * Use specific terms like "unemployment rate" or "consumer price index"
  * Searches are case-insensitive
  * Multiple words are searched as phrases
  * Partial matches are included
</ParamField>

<ParamField type="string">
  Type of search to perform.

  **Options:**

  * `full_text`: Search titles and descriptions
  * `series_id`: Search by exact series ID match
</ParamField>

<ParamField type="string">
  Comma-separated list of tags to filter by. All specified tags must be present.

  **Common tags:**

  * Geographic: `usa`, `state`, `county`, `msa`
  * Frequency: `daily`, `weekly`, `monthly`, `quarterly`, `annual`
  * Adjustment: `sa` (seasonally adjusted), `nsa` (not seasonally adjusted)
  * Topic: `gdp`, `inflation`, `employment`, `housing`, `interest rate`

  **Example:** `"monthly,sa,employment"`
</ParamField>

<ParamField type="string">
  Comma-separated list of tags to exclude. Series with these tags will be filtered out.

  **Example:** `"discontinued,projection"`
</ParamField>

<ParamField type="number">
  Maximum number of results to return (1-1000).
</ParamField>

<ParamField type="number">
  Number of results to skip for pagination.
</ParamField>

<ParamField type="string">
  Field to order results by.

  **Options:**

  * `search_rank`: Relevance to search terms
  * `series_id`: Alphabetical by ID
  * `title`: Alphabetical by title
  * `popularity`: Most accessed series first
  * `last_updated`: Most recently updated
  * `observation_start`: Earliest data first
  * `observation_end`: Latest data first
  * `frequency`: Grouped by frequency
  * `units`: Grouped by units
</ParamField>

<ParamField type="string">
  Sort order for results.

  **Options:**

  * `asc`: Ascending order
  * `desc`: Descending order
</ParamField>

<ParamField type="string">
  Variable to filter by.

  **Options:**

  * `frequency`: Filter by data frequency
  * `units`: Filter by measurement units
  * `seasonal_adjustment`: Filter by adjustment type
</ParamField>

<ParamField type="string">
  Value to filter the variable by. Must be used with `filter_variable`.

  **Frequency values:**

  * `d`: Daily
  * `w`: Weekly
  * `m`: Monthly
  * `q`: Quarterly
  * `a`: Annual

  **Units values:**

  * `lin`: Levels
  * `pch`: Percent change
  * `pc1`: Percent change from year ago
  * `index`: Index values

  **Seasonal adjustment values:**

  * `sa`: Seasonally adjusted
  * `nsa`: Not seasonally adjusted
</ParamField>

## Examples

### Basic Keyword Search

<CodeGroup>
  ```json Request theme={null}
  {
    "tool": "fred_search",
    "params": {
      "search_text": "unemployment rate",
      "limit": 5
    }
  }
  ```

  ```json Response theme={null}
  {
    "series": [
      {
        "id": "UNRATE",
        "title": "Unemployment Rate",
        "observation_start": "1948-01-01",
        "observation_end": "2024-12-01",
        "frequency": "Monthly",
        "units": "Percent",
        "seasonal_adjustment": "Seasonally Adjusted",
        "popularity": 98,
        "tags": ["usa", "monthly", "sa", "labor", "unemployment"]
      },
      {
        "id": "U6RATE",
        "title": "Total Unemployed, Plus All Marginally Attached Workers",
        "observation_start": "1994-01-01",
        "observation_end": "2024-12-01",
        "frequency": "Monthly",
        "units": "Percent",
        "seasonal_adjustment": "Seasonally Adjusted",
        "popularity": 85,
        "tags": ["usa", "monthly", "sa", "labor", "u6"]
      }
    ],
    "metadata": {
      "count": 5,
      "total": 1247
    }
  }
  ```
</CodeGroup>

### Search with Tag Filtering

<CodeGroup>
  ```json Request theme={null}
  {
    "tool": "fred_search",
    "params": {
      "search_text": "inflation",
      "tag_names": "usa,monthly,sa",
      "limit": 3
    }
  }
  ```

  ```json Response theme={null}
  {
    "series": [
      {
        "id": "CPIAUCSL",
        "title": "Consumer Price Index for All Urban Consumers: All Items",
        "frequency": "Monthly",
        "units": "Index 1982-1984=100",
        "seasonal_adjustment": "Seasonally Adjusted",
        "tags": ["usa", "monthly", "sa", "cpi", "inflation", "price"]
      },
      {
        "id": "CPILFESL",
        "title": "Consumer Price Index: All Items Less Food and Energy",
        "frequency": "Monthly",
        "units": "Index 1982-1984=100",
        "seasonal_adjustment": "Seasonally Adjusted",
        "tags": ["usa", "monthly", "sa", "core cpi", "inflation"]
      },
      {
        "id": "PCEPI",
        "title": "Personal Consumption Expenditures: Chain-type Price Index",
        "frequency": "Monthly",
        "units": "Index 2017=100",
        "seasonal_adjustment": "Seasonally Adjusted",
        "tags": ["usa", "monthly", "sa", "pce", "inflation"]
      }
    ]
  }
  ```
</CodeGroup>

### Filter by Frequency

<CodeGroup>
  ```json Request theme={null}
  {
    "tool": "fred_search",
    "params": {
      "search_text": "gdp",
      "filter_variable": "frequency",
      "filter_value": "q",
      "order_by": "popularity",
      "limit": 5
    }
  }
  ```

  ```json Response theme={null}
  {
    "series": [
      {
        "id": "GDP",
        "title": "Gross Domestic Product",
        "frequency": "Quarterly",
        "units": "Billions of Dollars",
        "seasonal_adjustment": "Seasonally Adjusted Annual Rate"
      },
      {
        "id": "GDPC1",
        "title": "Real Gross Domestic Product",
        "frequency": "Quarterly",
        "units": "Billions of Chained 2017 Dollars",
        "seasonal_adjustment": "Seasonally Adjusted Annual Rate"
      }
    ]
  }
  ```
</CodeGroup>

### Search by Series ID

<CodeGroup>
  ```json Request theme={null}
  {
    "tool": "fred_search",
    "params": {
      "search_text": "DGS10",
      "search_type": "series_id"
    }
  }
  ```

  ```json Response theme={null}
  {
    "series": [
      {
        "id": "DGS10",
        "title": "Market Yield on U.S. Treasury Securities at 10-Year Constant Maturity",
        "frequency": "Daily",
        "units": "Percent",
        "observation_start": "1962-01-02",
        "observation_end": "2024-12-31"
      }
    ]
  }
  ```
</CodeGroup>

### Exclude Discontinued Series

<CodeGroup>
  ```json Request theme={null}
  {
    "tool": "fred_search",
    "params": {
      "search_text": "federal funds",
      "exclude_tag_names": "discontinued",
      "limit": 5
    }
  }
  ```

  ```json Response theme={null}
  {
    "series": [
      {
        "id": "DFF",
        "title": "Federal Funds Effective Rate",
        "frequency": "Daily",
        "status": "Active"
      },
      {
        "id": "FEDFUNDS",
        "title": "Federal Funds Effective Rate",
        "frequency": "Monthly",
        "status": "Active"
      }
    ]
  }
  ```
</CodeGroup>

## Search Strategies

### Finding Economic Indicators

<Tabs>
  <Tab title="GDP & Growth">
    ```json theme={null}
    {
      "search_text": "gross domestic product",
      "tag_names": "usa,gdp",
      "filter_variable": "frequency",
      "filter_value": "q"
    }
    ```

    **Key Series:**

    * GDP: Nominal GDP
    * GDPC1: Real GDP
    * GDPPOT: Potential GDP
    * NYGDPMKTPCDWLD: World GDP Per Capita
  </Tab>

  <Tab title="Inflation">
    ```json theme={null}
    {
      "search_text": "consumer price",
      "tag_names": "usa,monthly,inflation",
      "order_by": "popularity"
    }
    ```

    **Key Series:**

    * CPIAUCSL: CPI All Items
    * CPILFESL: Core CPI
    * PCEPI: PCE Price Index
    * DFEDTARU: Fed Target Rate
  </Tab>

  <Tab title="Employment">
    ```json theme={null}
    {
      "search_text": "employment",
      "tag_names": "usa,monthly,sa",
      "exclude_tag_names": "discontinued"
    }
    ```

    **Key Series:**

    * PAYEMS: Nonfarm Payrolls
    * UNRATE: Unemployment Rate
    * CIVPART: Labor Force Participation
    * EMRATIO: Employment-Population Ratio
  </Tab>

  <Tab title="Housing">
    ```json theme={null}
    {
      "search_text": "housing",
      "tag_names": "usa,monthly",
      "filter_variable": "seasonal_adjustment",
      "filter_value": "sa"
    }
    ```

    **Key Series:**

    * HOUST: Housing Starts
    * PERMIT: Building Permits
    * CSUSHPISA: Case-Shiller Index
    * MORTGAGE30US: 30-Year Mortgage Rate
  </Tab>
</Tabs>

### Regional Data Search

```json theme={null}
// State-level unemployment
{
  "search_text": "unemployment rate",
  "tag_names": "state,monthly",
  "limit": 50
}

// Metropolitan area GDP
{
  "search_text": "gdp",
  "tag_names": "msa,annual",
  "order_by": "title"
}

// County-level income
{
  "search_text": "personal income",
  "tag_names": "county,annual"
}
```

### International Data Search

```json theme={null}
// Global inflation rates
{
  "search_text": "inflation",
  "tag_names": "international,monthly",
  "exclude_tag_names": "usa"
}

// Exchange rates
{
  "search_text": "exchange rate",
  "tag_names": "daily,currency"
}

// International GDP comparison
{
  "search_text": "gdp growth",
  "tag_names": "international,annual,oecd"
}
```

## Common Tag Combinations

### By Geography

| Scope         | Tags            | Example Series         |
| ------------- | --------------- | ---------------------- |
| National      | `usa`           | UNRATE, GDP, CPIAUCSL  |
| State         | `state`         | CAUNRATE, CASTPRHHRSA  |
| Metro         | `msa`           | ATXURN, DALPRHHRSA     |
| County        | `county`        | PCPI01001, CAUNTY01001 |
| International | `international` | LRHUTTTTJPM156S        |

### By Frequency

| Frequency | Tag         | Common Uses                    |
| --------- | ----------- | ------------------------------ |
| Daily     | `daily`     | Interest rates, exchange rates |
| Weekly    | `weekly`    | Initial jobless claims         |
| Monthly   | `monthly`   | CPI, employment, retail sales  |
| Quarterly | `quarterly` | GDP, corporate profits         |
| Annual    | `annual`    | Population, long-term trends   |

### By Topic

| Topic             | Common Tags                       | Key Series          |
| ----------------- | --------------------------------- | ------------------- |
| Monetary Policy   | `fed, interest rate, monetary`    | DFF, DFEDTARU       |
| Inflation         | `inflation, cpi, price`           | CPIAUCSL, PCEPI     |
| Labor Market      | `employment, labor, unemployment` | UNRATE, PAYEMS      |
| Financial Markets | `stock, bond, yield`              | SP500, DGS10        |
| Housing           | `housing, real estate, mortgage`  | HOUST, MORTGAGE30US |

## Advanced Search Patterns

### Complex Queries

```json theme={null}
// Find all seasonally adjusted monthly employment data for California
{
  "search_text": "employment",
  "tag_names": "california,monthly,sa",
  "filter_variable": "units",
  "filter_value": "lin",
  "order_by": "popularity"
}

// Get high-frequency financial indicators
{
  "search_text": "financial",
  "tag_names": "daily",
  "exclude_tag_names": "discontinued,forecast",
  "order_by": "last_updated",
  "limit": 20
}

// Find recession indicators
{
  "search_text": "recession",
  "tag_names": "usa,monthly",
  "order_by": "popularity",
  "limit": 10
}
```

### Pagination for Large Results

```json theme={null}
// First page
{
  "search_text": "interest rate",
  "limit": 100,
  "offset": 0
}

// Second page
{
  "search_text": "interest rate",
  "limit": 100,
  "offset": 100
}

// Third page
{
  "search_text": "interest rate",
  "limit": 100,
  "offset": 200
}
```

## Error Handling

### Common Errors

| Error                   | Cause                            | Solution                                  |
| ----------------------- | -------------------------------- | ----------------------------------------- |
| `No results found`      | Search too specific              | Broaden search terms or remove filters    |
| `Invalid tag_names`     | Malformed tag list               | Use comma-separated values without spaces |
| `Invalid filter_value`  | Wrong value for filter\_variable | Check valid values for the filter type    |
| `Limit exceeds maximum` | limit > 1000                     | Use limit ≤ 1000 and pagination           |

## Best Practices

<Steps>
  <Step title="Start Broad">
    Begin with general terms and progressively add filters
  </Step>

  <Step title="Use Tags Effectively">
    Combine geographic, frequency, and topic tags for precision
  </Step>

  <Step title="Sort by Popularity">
    Popular series are often the most reliable and widely used
  </Step>

  <Step title="Exclude Discontinued">
    Add `exclude_tag_names: "discontinued"` for active series only
  </Step>

  <Step title="Check Metadata">
    Review frequency, units, and seasonal adjustment before using data
  </Step>
</Steps>

## Related Tools

<CardGroup>
  <Card title="fred_browse" icon="folder-tree" href="/api-reference/fred-browse">
    Browse categories systematically
  </Card>

  <Card title="fred_get_series" icon="chart-line" href="/api-reference/fred-get-series">
    Retrieve data for found series
  </Card>
</CardGroup>


# API Overview
Source: https://fred-mcp-server.amorelli.tech/api-reference/overview

Complete reference for FRED MCP Server tools

# API Reference Overview

The FRED MCP Server provides three powerful tools that give you complete access to the Federal Reserve Economic Data (FRED) database containing over 800,000 economic time series.

## Available Tools

<CardGroup>
  <Card title="fred_browse" icon="folder-tree" href="/api-reference/fred-browse">
    Navigate FRED's catalog through categories, releases, and sources
  </Card>

  <Card title="fred_search" icon="magnifying-glass" href="/api-reference/fred-search">
    Search for economic data series by keywords, tags, or filters
  </Card>

  <Card title="fred_get_series" icon="chart-line" href="/api-reference/fred-get-series">
    Retrieve time series data with transformations and aggregations
  </Card>
</CardGroup>

## Tool Capabilities

### Data Discovery & Navigation

The **`fred_browse`** and **`fred_search`** tools work together to help you discover relevant economic data:

<AccordionGroup>
  <Accordion title="Browse by Category">
    Navigate through hierarchical categories like:

    * Money, Banking & Finance
    * Population, Employment & Labor Markets
    * Production & Business Activity
    * International Data
  </Accordion>

  <Accordion title="Search by Keywords">
    Find series using:

    * Full-text search across titles and descriptions
    * Tag-based filtering (e.g., "gdp", "monthly", "seasonally-adjusted")
    * Combined search criteria
  </Accordion>

  <Accordion title="Filter by Attributes">
    Narrow results by:

    * Frequency (daily, weekly, monthly, quarterly, annual)
    * Units (levels, percent change, index)
    * Seasonal adjustment status
    * Geographic region
  </Accordion>
</AccordionGroup>

### Data Retrieval & Transformation

The **`fred_get_series`** tool provides comprehensive data access:

<AccordionGroup>
  <Accordion title="Time Series Data">
    * Historical observations dating back decades
    * Real-time data updates
    * Custom date ranges
    * Vintage data for point-in-time analysis
  </Accordion>

  <Accordion title="Built-in Transformations">
    * Growth rates and percent changes
    * Year-over-year comparisons
    * Logarithmic transformations
    * Moving averages
    * Frequency conversions
  </Accordion>

  <Accordion title="Aggregation Methods">
    * Average over periods
    * Sum of values
    * End-of-period observations
    * Custom sampling frequencies
  </Accordion>
</AccordionGroup>

## Response Formats

All tools return structured JSON responses:

### Success Response Structure

```json theme={null}
{
  "type": "text",
  "text": "Successfully retrieved data",
  "data": {
    // Tool-specific data structure
  },
  "metadata": {
    "count": 100,
    "offset": 0,
    "limit": 100,
    "total": 500
  }
}
```

### Error Response Structure

```json theme={null}
{
  "type": "text",
  "text": "Error message describing the issue",
  "error": {
    "code": "INVALID_SERIES_ID",
    "message": "The series ID 'INVALID' was not found",
    "details": {
      // Additional error context
    }
  }
}
```

## Common Parameters

Many parameters are shared across tools:

<ParamField type="number">
  Maximum number of results to return. Range varies by tool:

  * Search: 1-1000
  * Browse: 1-1000
  * Series: 1-100000
</ParamField>

<ParamField type="number">
  Number of results to skip for pagination. Useful for retrieving large result sets.
</ParamField>

<ParamField type="string">
  Sort order for results:

  * `asc`: Ascending order
  * `desc`: Descending order
</ParamField>

<ParamField type="string">
  Field to sort results by. Options vary by tool but commonly include:

  * `series_id`: Alphabetical by ID
  * `title`: Alphabetical by title
  * `popularity`: Most frequently accessed
  * `last_updated`: Most recently updated
</ParamField>

## Rate Limits

<Warning>
  FRED API has rate limits to ensure fair usage:

  * **120 requests per minute** for general API calls
  * **40 requests per minute** for series observations
</Warning>

The server automatically handles rate limiting with:

* Exponential backoff on rate limit errors
* Request queuing
* Automatic retries with jitter

## Data Freshness

<Info>
  Data update frequency varies by series:

  * **Real-time series**: Updated within minutes of release
  * **Daily series**: Updated each business day
  * **Weekly/Monthly**: Updated per release schedule
  * **Quarterly/Annual**: Updated per official release calendar
</Info>

## Error Handling

Common error codes and their meanings:

| Error Code             | Description                           | Solution                                        |
| ---------------------- | ------------------------------------- | ----------------------------------------------- |
| `INVALID_API_KEY`      | API key is invalid or missing         | Check your FRED API key configuration           |
| `SERIES_NOT_FOUND`     | Requested series ID doesn't exist     | Verify the series ID or search for alternatives |
| `RATE_LIMIT_EXCEEDED`  | Too many requests                     | Wait and retry, or reduce request frequency     |
| `INVALID_DATE_RANGE`   | Date parameters are invalid           | Use YYYY-MM-DD format and ensure start \< end   |
| `TRANSFORMATION_ERROR` | Cannot apply requested transformation | Check if transformation is valid for the series |

## Best Practices

<Steps>
  <Step title="Start with Search or Browse">
    Don't guess series IDs. Use `fred_search` or `fred_browse` to discover available data.
  </Step>

  <Step title="Use Appropriate Limits">
    Start with smaller limits and increase as needed. Large requests may timeout.
  </Step>

  <Step title="Respect Rate Limits">
    Plan queries carefully and respect FRED API rate limits. Review FRED's terms of use.
  </Step>

  <Step title="Handle Errors Gracefully">
    Always check for error responses and have fallback strategies.
  </Step>
</Steps>

## Tool Comparison

| Feature             | fred\_browse               | fred\_search             | fred\_get\_series     |
| ------------------- | -------------------------- | ------------------------ | --------------------- |
| **Purpose**         | Navigate catalog           | Find specific series     | Retrieve data         |
| **Input**           | Category/Release IDs       | Keywords/Tags            | Series ID             |
| **Output**          | Lists of categories/series | Matching series          | Time series data      |
| **Best For**        | Exploring available data   | Finding known indicators | Getting actual values |
| **Pagination**      | ✅ Yes                      | ✅ Yes                    | ✅ Yes                 |
| **Filtering**       | Basic                      | Advanced                 | N/A                   |
| **Transformations** | ❌ No                       | ❌ No                     | ✅ Yes                 |

## Integration Examples

<CodeGroup>
  ```javascript JavaScript/Node.js theme={null}
  // Using with an MCP client
  const client = new MCPClient();

  // Browse categories
  const categories = await client.callTool('fred_browse', {
    browse_type: 'categories'
  });

  // Search for inflation
  const results = await client.callTool('fred_search', {
    search_text: 'inflation',
    tag_names: 'monthly,sa'
  });

  // Get CPI data
  const cpi = await client.callTool('fred_get_series', {
    series_id: 'CPIAUCSL',
    units: 'pc1'  // Year-over-year % change
  });
  ```

  ```python Python theme={null}
  # Using with Python MCP client
  import mcp_client

  client = mcp_client.Client()

  # Browse economic releases
  releases = client.call_tool('fred_browse', {
      'browse_type': 'releases',
      'limit': 10
  })

  # Search for employment data
  employment = client.call_tool('fred_search', {
      'search_text': 'employment',
      'filter_variable': 'frequency',
      'filter_value': 'm'  # Monthly only
  })

  # Get unemployment rate
  unemployment = client.call_tool('fred_get_series', {
      'series_id': 'UNRATE',
      'observation_start': '2024-01-01'
  })
  ```

  ```bash Command Line theme={null}
  # Using with curl and jq

  # Browse sources
  curl -X POST http://localhost:3000/tool/call \
    -H "Content-Type: application/json" \
    -d '{
      "tool": "fred_browse",
      "params": {"browse_type": "sources"}
    }' | jq .

  # Search for GDP
  curl -X POST http://localhost:3000/tool/call \
    -H "Content-Type: application/json" \
    -d '{
      "tool": "fred_search",
      "params": {"search_text": "gross domestic product"}
    }' | jq .

  # Get GDP data
  curl -X POST http://localhost:3000/tool/call \
    -H "Content-Type: application/json" \
    -d '{
      "tool": "fred_get_series",
      "params": {"series_id": "GDP"}
    }' | jq .
  ```
</CodeGroup>

## Next Steps

<CardGroup>
  <Card title="fred_browse" icon="folder-tree" href="/api-reference/fred-browse">
    Browse tool reference
  </Card>

  <Card title="fred_search" icon="magnifying-glass" href="/api-reference/fred-search">
    Search tool reference
  </Card>

  <Card title="fred_get_series" icon="chart-line" href="/api-reference/fred-get-series">
    Series tool reference
  </Card>
</CardGroup>


# Changelog
Source: https://fred-mcp-server.amorelli.tech/community/changelog

Version history and release notes

# Changelog

All notable changes to the FRED MCP Server are documented here.

## \[1.0.2] - 2024-10-20

### Added

* Comprehensive documentation
* Zenodo DOI for citations
* Enhanced error handling

### Changed

* Updated dependencies
* Improved TypeScript types

### Fixed

* Rate limiting edge cases
* Search result pagination

## \[1.0.1] - 2024-09-15

### Fixed

* Authentication error messages
* Series observation retrieval

## \[1.0.0] - 2024-09-01

### Added

* Initial release
* Three core tools: fred\_search, fred\_browse, fred\_get\_series
* MCP protocol implementation
* TypeScript support

## Versioning

This project follows [Semantic Versioning](https://semver.org/):

* **MAJOR**: Breaking changes
* **MINOR**: New features (backward-compatible)
* **PATCH**: Bug fixes (backward-compatible)

## Release Process

1. Update version in package.json
2. Update CHANGELOG.md
3. Create git tag
4. Publish to npm
5. Create GitHub release

## Next Steps

<CardGroup>
  <Card title="Installation" icon="download" href="/installation">
    Install latest version
  </Card>

  <Card title="GitHub Releases" icon="github" href="https://github.com/stefanoamorelli/fred-mcp-server/releases">
    View all releases
  </Card>
</CardGroup>


# Code of Conduct
Source: https://fred-mcp-server.amorelli.tech/community/code-of-conduct

Community guidelines and expectations

# Code of Conduct

## Our Pledge

We are committed to providing a welcoming and inclusive environment for all contributors.

## Our Standards

**Positive behavior includes:**

* Being respectful and considerate
* Welcoming diverse perspectives
* Accepting constructive criticism
* Focusing on what's best for the community
* Showing empathy towards others

**Unacceptable behavior includes:**

* Harassment or discriminatory language
* Personal attacks or trolling
* Publishing private information
* Other conduct inappropriate in a professional setting

## Enforcement

Project maintainers are responsible for clarifying and enforcing standards. Instances of unacceptable behavior may be reported to [stefano@amorelli.tech](mailto:stefano@amorelli.tech).

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

## Next Steps

<CardGroup>
  <Card title="Contributing" icon="code-pull-request" href="/community/contributing">
    How to contribute
  </Card>

  <Card title="Security" icon="shield" href="/community/security">
    Report security issues
  </Card>
</CardGroup>


# Contributing
Source: https://fred-mcp-server.amorelli.tech/community/contributing

How to contribute to FRED MCP Server

# Contributing

We welcome contributions to the FRED MCP Server! This guide will help you get started.

## Ways to Contribute

<CardGroup>
  <Card title="Report Bugs" icon="bug">
    Found an issue? Let us know on GitHub Issues
  </Card>

  <Card title="Suggest Features" icon="lightbulb">
    Have an idea? Open a feature request
  </Card>

  <Card title="Improve Docs" icon="book">
    Help make documentation clearer
  </Card>

  <Card title="Submit Code" icon="code">
    Fix bugs or add features via pull requests
  </Card>
</CardGroup>

## Development Setup

<Steps>
  <Step title="Fork the Repository">
    Fork [fred-mcp-server](https://github.com/stefanoamorelli/fred-mcp-server) on GitHub
  </Step>

  <Step title="Clone Your Fork">
    ```bash theme={null}
    git clone https://github.com/YOUR_USERNAME/fred-mcp-server.git
    cd fred-mcp-server
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    pnpm install
    ```
  </Step>

  <Step title="Build the Project">
    ```bash theme={null}
    pnpm run build
    ```
  </Step>

  <Step title="Run Tests">
    ```bash theme={null}
    pnpm test
    ```
  </Step>
</Steps>

## Making Changes

### Code Style

* Follow existing code style
* Use TypeScript for type safety
* Add tests for new features
* Update documentation

### Testing

```bash theme={null}
# Run all tests
pnpm test

# Run specific test
pnpm test -- registry.test.ts

# Watch mode
pnpm run test:watch
```

### Commits

Use conventional commit messages:

```
feat: add new search filter
fix: resolve rate limiting issue
docs: update installation guide
test: add tests for browse functionality
```

## Pull Requests

<Steps>
  <Step title="Create Branch">
    ```bash theme={null}
    git checkout -b feature/your-feature-name
    ```
  </Step>

  <Step title="Make Changes">
    Write code, add tests, update docs
  </Step>

  <Step title="Run Tests">
    Ensure all tests pass
  </Step>

  <Step title="Commit">
    ```bash theme={null}
    git commit -m "feat: your feature description"
    ```
  </Step>

  <Step title="Push">
    ```bash theme={null}
    git push origin feature/your-feature-name
    ```
  </Step>

  <Step title="Open PR">
    Create pull request on GitHub
  </Step>
</Steps>

## Code of Conduct

Please read and follow our [Code of Conduct](/community/code-of-conduct).

## Questions?

* GitHub Discussions
* Open an issue
* Email: [stefano@amorelli.tech](mailto:stefano@amorelli.tech)

## Next Steps

<CardGroup>
  <Card title="Code of Conduct" icon="handshake" href="/community/code-of-conduct">
    Community guidelines
  </Card>

  <Card title="Security" icon="shield" href="/community/security">
    Report security issues
  </Card>
</CardGroup>


# License
Source: https://fred-mcp-server.amorelli.tech/community/license

AGPL-3.0 License information

# License

FRED MCP Server is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

## AGPL-3.0 License

This is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

### Key Terms

<AccordionGroup>
  <Accordion title="Freedom to Use">
    You can use this software for any purpose, including commercial use.
  </Accordion>

  <Accordion title="Freedom to Study">
    You can study how the program works and modify it.
  </Accordion>

  <Accordion title="Freedom to Distribute">
    You can redistribute copies to help others.
  </Accordion>

  <Accordion title="Freedom to Improve">
    You can distribute modified versions.
  </Accordion>

  <Accordion title="Network Use Requirement">
    If you run modified software as a network service, you must make your source code available to users.
  </Accordion>
</AccordionGroup>

### No Warranty

This program is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## Full License Text

The complete license text is available at:

* [GNU.org](https://www.gnu.org/licenses/agpl-3.0.en.html)
* [GitHub Repository](https://github.com/stefanoamorelli/fred-mcp-server/blob/main/LICENSE)

## Third-Party Licenses

This project uses:

* **@modelcontextprotocol/sdk**: MIT License
* **zod**: MIT License

See package.json for complete dependency list.

## FRED Data License

Note: FRED data has separate terms of use from the St. Louis Federal Reserve. See [FRED Terms](https://fred.stlouisfed.org/docs/api/terms_of_use.html).

## Questions?

For licensing questions, contact: [stefano@amorelli.tech](mailto:stefano@amorelli.tech)

## Next Steps

<CardGroup>
  <Card title="Contributing" icon="code-pull-request" href="/community/contributing">
    Contribute to the project
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/stefanoamorelli/fred-mcp-server">
    View source code
  </Card>
</CardGroup>


# Security
Source: https://fred-mcp-server.amorelli.tech/community/security

Security policy and vulnerability reporting

# Security Policy

## Supported Versions

| Version | Supported |
| ------- | --------- |
| 1.x.x   | ✅ Yes     |
| \< 1.0  | ❌ No      |

## Reporting a Vulnerability

If you discover a security vulnerability, please email [stefano@amorelli.tech](mailto:stefano@amorelli.tech) instead of using the public issue tracker.

Include:

* Description of the vulnerability
* Steps to reproduce
* Potential impact
* Suggested fix (if any)

## Response Timeline

* **Acknowledgment**: Within 48 hours
* **Initial Assessment**: Within 1 week
* **Fix Timeline**: Varies by severity
* **Public Disclosure**: After fix is released

## Security Best Practices

<AccordionGroup>
  <Accordion title="API Key Protection">
    * Never commit API keys to version control
    * Use environment variables
    * Rotate keys periodically
    * Use separate keys for dev/prod
  </Accordion>

  <Accordion title="Dependency Security">
    * Keep dependencies updated
    * Review security advisories
    * Use `npm audit` regularly
  </Accordion>

  <Accordion title="Safe Usage">
    * Validate all user inputs
    * Don't expose keys in logs
    * Use HTTPS for API calls
    * Implement rate limiting
  </Accordion>
</AccordionGroup>

## Known Issues

Check [GitHub Security Advisories](https://github.com/stefanoamorelli/fred-mcp-server/security/advisories) for current issues.

## Next Steps

<CardGroup>
  <Card title="Authentication" icon="key" href="/core-concepts/authentication">
    API key setup
  </Card>

  <Card title="Contributing" icon="code-pull-request" href="/community/contributing">
    Contribute securely
  </Card>
</CardGroup>


# Configuration
Source: https://fred-mcp-server.amorelli.tech/configuration

Complete configuration guide for FRED MCP Server

# Configuration

This guide covers all configuration options for the FRED MCP Server, including environment variables, client setup, and advanced settings.

## Environment Variables

The FRED MCP Server uses environment variables for configuration. These can be set in your client configuration or system environment.

### Required Variables

<ParamField type="string">
  Your FRED API key from the Federal Reserve Bank of St. Louis.

  **How to obtain:**

  1. Visit [fred.stlouisfed.org/docs/api/api\_key.html](https://fred.stlouisfed.org/docs/api/api_key.html)
  2. Register for a free account
  3. Request an API key (instant approval)

  <Warning>
    Never commit your API key to version control. Use environment variables or secure key management.
  </Warning>
</ParamField>

### Optional Variables

<ParamField type="string">
  Override the FRED API base URL. Useful for:

  * Using proxy servers
  * Testing with mock services
  * Enterprise deployments with custom endpoints
</ParamField>

<ParamField type="string">
  Control the verbosity of server logs.

  **Options:**

  * `debug`: Detailed debugging information
  * `info`: General information messages
  * `warn`: Warning messages only
  * `error`: Error messages only
</ParamField>

<ParamField type="number">
  Maximum number of retry attempts for failed API requests.
</ParamField>

<ParamField type="number">
  Request timeout in milliseconds (default: 30 seconds).
</ParamField>

## Client Configurations

### Claude Desktop

<Tabs>
  <Tab title="Basic Configuration">
    ```json theme={null}
    {
      "mcpServers": {
        "fred-mcp": {
          "command": "fred-mcp-server",
          "env": {
            "FRED_API_KEY": "your_api_key_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Advanced Configuration">
    ```json theme={null}
    {
      "mcpServers": {
        "fred-mcp": {
          "command": "fred-mcp-server",
          "env": {
            "FRED_API_KEY": "your_api_key_here",
            "LOG_LEVEL": "debug",
            "MAX_RETRIES": "5",
            "TIMEOUT_MS": "60000"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Multiple Instances">
    ```json theme={null}
    {
      "mcpServers": {
        "fred-production": {
          "command": "fred-mcp-server",
          "env": {
            "FRED_API_KEY": "production_key"
          }
        },
        "fred-development": {
          "command": "fred-mcp-server",
          "env": {
            "FRED_API_KEY": "development_key",
            "LOG_LEVEL": "debug"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Docker Configuration

<AccordionGroup>
  <Accordion title="Docker Run Configuration">
    ```bash theme={null}
    docker run -i --rm \
      -e FRED_API_KEY="your_api_key" \
      -e LOG_LEVEL="info" \
      -e MAX_RETRIES="3" \
      -e TIMEOUT_MS="30000" \
      stefanoamorelli/fred-mcp-server:latest
    ```
  </Accordion>

  <Accordion title="Docker Compose Configuration">
    ```yaml theme={null}
    version: '3.8'

    services:
      fred-mcp:
        image: stefanoamorelli/fred-mcp-server:latest
        environment:
          - FRED_API_KEY=${FRED_API_KEY}
          - LOG_LEVEL=info
          - MAX_RETRIES=3
          - TIMEOUT_MS=30000
        stdin_open: true
        tty: false
    ```
  </Accordion>

  <Accordion title="Kubernetes Deployment">
    ```yaml theme={null}
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: fred-mcp-server
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: fred-mcp
      template:
        metadata:
          labels:
            app: fred-mcp
        spec:
          containers:
          - name: fred-mcp
            image: stefanoamorelli/fred-mcp-server:latest
            env:
            - name: FRED_API_KEY
              valueFrom:
                secretKeyRef:
                  name: fred-secrets
                  key: api-key
            - name: LOG_LEVEL
              value: "info"
    ```
  </Accordion>
</AccordionGroup>

## Security Best Practices

### API Key Management

<Warning>
  Never expose your FRED API key in public repositories, logs, or client-side code.
</Warning>

<Tabs>
  <Tab title="Environment Files">
    Use `.env` files with proper gitignore:

    ```bash theme={null}
    # .env
    FRED_API_KEY=your_secure_key_here
    ```

    ```bash theme={null}
    # .gitignore
    .env
    .env.local
    .env.*.local
    ```

    Load in your application:

    ```javascript theme={null}
    require('dotenv').config();
    const apiKey = process.env.FRED_API_KEY;
    ```
  </Tab>

  <Tab title="Secret Managers">
    Use platform-specific secret managers:

    **AWS Secrets Manager:**

    ```javascript theme={null}
    const AWS = require('aws-sdk');
    const client = new AWS.SecretsManager();

    const secret = await client.getSecretValue({
      SecretId: "fred-api-key"
    }).promise();
    ```

    **Azure Key Vault:**

    ```javascript theme={null}
    const { SecretClient } = require("@azure/keyvault-secrets");
    const client = new SecretClient(vaultUrl, credential);
    const secret = await client.getSecret("fred-api-key");
    ```
  </Tab>

  <Tab title="CI/CD Secrets">
    Configure in your CI/CD pipeline:

    **GitHub Actions:**

    ```yaml theme={null}
    steps:
      - name: Run FRED MCP
        env:
          FRED_API_KEY: ${{ secrets.FRED_API_KEY }}
        run: |
          fred-mcp-server
    ```

    **GitLab CI:**

    ```yaml theme={null}
    variables:
      FRED_API_KEY: $FRED_API_KEY  # Set in GitLab settings
    ```
  </Tab>
</Tabs>

### Network Security

<AccordionGroup>
  <Accordion title="Firewall Configuration">
    If running as a service, restrict network access:

    ```bash theme={null}
    # iptables example
    iptables -A INPUT -p tcp --dport 3000 -s 127.0.0.1 -j ACCEPT
    iptables -A INPUT -p tcp --dport 3000 -j DROP
    ```
  </Accordion>

  <Accordion title="TLS/SSL Configuration">
    For production deployments with HTTP transport:

    ```javascript theme={null}
    // Use with reverse proxy (recommended)
    // nginx.conf
    server {
      listen 443 ssl;
      ssl_certificate /path/to/cert.pem;
      ssl_certificate_key /path/to/key.pem;

      location /fred-mcp {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Performance Optimization

### Rate Limiting

FRED API has rate limits that you must respect:

<Info>
  Default FRED API limits:

  * 120 requests per minute
  * 40 requests per minute for series observations
</Info>

<ParamField type="number">
  Maximum requests per minute
</ParamField>

<ParamField type="boolean">
  Enable exponential backoff on rate limit errors
</ParamField>

## Logging Configuration

### Log Formats

<Tabs>
  <Tab title="JSON Logging">
    ```bash theme={null}
    export LOG_FORMAT="json"
    export LOG_LEVEL="info"

    # Output:
    # {"timestamp":"2025-01-20T10:30:45Z","level":"info","message":"Server started"}
    ```
  </Tab>

  <Tab title="Text Logging">
    ```bash theme={null}
    export LOG_FORMAT="text"
    export LOG_LEVEL="debug"

    # Output:
    # 2025-01-20 10:30:45 [INFO] Server started
    # 2025-01-20 10:30:46 [DEBUG] Processing request...
    ```
  </Tab>
</Tabs>

### Log Destinations

<AccordionGroup>
  <Accordion title="File Logging">
    ```bash theme={null}
    # Redirect to file
    fred-mcp-server > /var/log/fred-mcp.log 2>&1

    # With rotation
    fred-mcp-server | rotatelogs /var/log/fred-mcp-%Y%m%d.log 86400
    ```
  </Accordion>

  <Accordion title="Syslog Integration">
    ```bash theme={null}
    # Send to syslog
    fred-mcp-server | logger -t fred-mcp -p local0.info
    ```
  </Accordion>
</AccordionGroup>

## Development Configuration

### Local Development

<Steps>
  <Step title="Create Development Config">
    ```json theme={null}
    // .claude/dev-config.json
    {
      "mcpServers": {
        "fred-dev": {
          "command": "node",
          "args": ["./build/index.js"],
          "cwd": "/path/to/fred-mcp-server",
          "env": {
            "FRED_API_KEY": "dev_key",
            "LOG_LEVEL": "debug",
            "NODE_ENV": "development"
          }
        }
      }
    }
    ```
  </Step>

  <Step title="Set Development Variables">
    ```bash theme={null}
    # .env.development
    FRED_API_KEY=your_dev_key
    LOG_LEVEL=debug
    NODE_ENV=development
    ```
  </Step>

  <Step title="Run Development Server">
    ```bash theme={null}
    # Load dev environment and run
    source .env.development
    npm run start
    ```
  </Step>
</Steps>

### Testing Configuration

<CodeGroup>
  ```javascript Jest Config theme={null}
  // jest.config.js
  module.exports = {
    testEnvironment: 'node',
    setupFiles: ['./test/setup.js'],
    env: {
      FRED_API_KEY: 'test_key',
      FRED_BASE_URL: 'http://localhost:3001/mock-fred',
      LOG_LEVEL: 'error'
    }
  };
  ```

  ```bash Mock Server theme={null}
  # Start mock FRED server for testing
  docker run -d -p 3001:3001 \
    -e MOCK_MODE=true \
    fred-mock-server
  ```

  ```typescript Test Setup theme={null}
  // test/setup.ts
  process.env.FRED_API_KEY = 'test_key';
  process.env.LOG_LEVEL = 'error';
  process.env.NODE_ENV = 'test';
  ```
</CodeGroup>

## Monitoring & Alerts

### Health Checks

Configure health monitoring:

<ParamField type="boolean">
  Enable health check endpoint
</ParamField>

<ParamField type="number">
  Health check interval in milliseconds
</ParamField>

### Metrics Collection

<AccordionGroup>
  <Accordion title="Prometheus Metrics">
    ```javascript theme={null}
    // Enable metrics collection
    export METRICS_ENABLED=true
    export METRICS_PORT=9090

    // Prometheus config
    scrape_configs:
      - job_name: 'fred-mcp'
        static_configs:
          - targets: ['localhost:9090']
    ```
  </Accordion>

  <Accordion title="Custom Metrics">
    ```javascript theme={null}
    // Track custom metrics
    export TRACK_USAGE=true
    export USAGE_REPORT_INTERVAL=3600000  // 1 hour
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting Configuration

### Debug Mode

Enable comprehensive debugging:

```bash theme={null}
# Maximum debugging
export LOG_LEVEL=debug
export DEBUG=fred:*
export NODE_DEBUG=mcp
export TRACE_REQUESTS=true

fred-mcp-server
```

### Common Issues

<AccordionGroup>
  <Accordion title="Configuration not loading">
    **Symptoms:** Default values used instead of configured values

    **Solutions:**

    1. Check JSON syntax in config file
    2. Verify environment variable names (case-sensitive)
    3. Ensure config file is saved
    4. Restart client application
  </Accordion>

  <Accordion title="Permission errors">
    **Symptoms:** Cannot read/write configuration

    **Solutions:**

    ```bash theme={null}
    # Fix permissions
    chmod 600 ~/.config/claude/claude_desktop_config.json
    chown $USER:$USER ~/.config/claude/claude_desktop_config.json
    ```
  </Accordion>

  <Accordion title="Environment variables not set">
    **Symptoms:** API key not found errors

    **Check variables:**

    ```bash theme={null}
    # Linux/Mac
    echo $FRED_API_KEY
    env | grep FRED

    # Windows
    echo %FRED_API_KEY%
    set | findstr FRED
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Explore available tools and parameters
  </Card>

  <Card title="Examples" icon="flask" href="/examples/basic-usage">
    See configuration in action
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/resources/troubleshooting">
    Solve common configuration issues
  </Card>

  <Card title="Security" icon="shield" href="/community/security">
    Security best practices
  </Card>
</CardGroup>


# Authentication
Source: https://fred-mcp-server.amorelli.tech/core-concepts/authentication

Setting up FRED API access and security

# Authentication

Access to the FRED API requires a free API key. This guide covers how to obtain and configure your API key securely.

## Getting an API Key

### Registration Process

<Steps>
  <Step title="Create Account">
    Visit [FRED API Registration](https://fredaccount.stlouisfed.org/apikeys) and create a free account
  </Step>

  <Step title="Request API Key">
    Click "Request API Key" and fill out the brief application form
  </Step>

  <Step title="Instant Approval">
    Your API key will be generated immediately and displayed on screen
  </Step>

  <Step title="Save Securely">
    Store your key securely - you'll need it for configuration
  </Step>
</Steps>

<Note>
  API keys are **completely free** with no usage fees. Rate limits apply but are generous for most use cases.
</Note>

### API Key Format

Keys are 32-character alphanumeric strings:

```
a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
```

## Configuration

### Environment Variables (Recommended)

The most secure method is using environment variables.

<Tabs>
  <Tab title="Claude Desktop (macOS)">
    Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "fred": {
          "command": "npx",
          "args": ["-y", "fred-mcp-server"],
          "env": {
            "FRED_API_KEY": "your-api-key-here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop (Windows)">
    Edit `%APPDATA%\Claude\claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "fred": {
          "command": "npx",
          "args": ["-y", "fred-mcp-server"],
          "env": {
            "FRED_API_KEY": "your-api-key-here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="System Environment">
    Add to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.):

    ```bash theme={null}
    export FRED_API_KEY="your-api-key-here"
    ```

    Then restart your terminal or run:

    ```bash theme={null}
    source ~/.bashrc  # or ~/.zshrc
    ```
  </Tab>

  <Tab title=".env File">
    Create `.env` file in your project directory:

    ```bash theme={null}
    FRED_API_KEY=your-api-key-here
    ```

    <Warning>
      Add `.env` to `.gitignore` to prevent committing secrets
    </Warning>
  </Tab>
</Tabs>

### Verification

Test your configuration:

```bash theme={null}
# Using the MCP server directly
FRED_API_KEY=your-key npx fred-mcp-server

# Or if set in environment
npx fred-mcp-server
```

The server should start without errors. If you see authentication errors, verify your key is correct.

## Security Best Practices

### Key Protection

<AccordionGroup>
  <Accordion title="Never Commit Keys">
    ❌ Don't:

    ```json theme={null}
    // config.json
    {
      "api_key": "a1b2c3d4e5f6g7h8..."
    }
    ```

    ✅ Do:

    ```json theme={null}
    // config.json (use environment variables)
    {
      "api_key": "${FRED_API_KEY}"
    }
    ```
  </Accordion>

  <Accordion title="Restrict File Permissions">
    Limit who can read configuration files:

    ```bash theme={null}
    chmod 600 ~/.claude/config.json
    chmod 600 .env
    ```
  </Accordion>

  <Accordion title="Use Separate Keys">
    Create different keys for:

    * Development environments
    * Production systems
    * Different applications

    This allows selective revocation if needed.
  </Accordion>

  <Accordion title="Regular Rotation">
    Periodically generate new keys and update your configuration
  </Accordion>
</AccordionGroup>

### Access Control

The FRED MCP Server never:

* Logs API keys
* Exposes keys in responses
* Stores keys persistently
* Transmits keys except to FRED API

Keys are only used for authenticated requests to `api.stlouisfed.org`.

## Rate Limits

FRED API implements rate limiting to ensure fair usage.

### Current Limits

| Limit Type          | Restriction | Notes                      |
| ------------------- | ----------- | -------------------------- |
| Requests per Minute | 120         | Across all endpoints       |
| Series Observations | 40/min      | Specific to data retrieval |
| Daily Requests      | Varies      | Based on account tier      |

### Handling Rate Limits

The MCP server implements automatic handling:

<CodeGroup>
  ```javascript Retry Logic theme={null}
  {
    maxRetries: 3,
    backoffMultiplier: 2,
    initialDelay: 1000 // ms
  }
  ```

  ```javascript Rate Limit Response theme={null}
  {
    "error": {
      "code": 429,
      "message": "Too Many Requests",
      "retryAfter": 60 // seconds
    }
  }
  ```
</CodeGroup>

### Best Practices

<Steps>
  <Step title="Batch Requests">
    Group related queries to minimize API calls
  </Step>

  <Step title="Use Date Ranges">
    Request only the time periods you need
  </Step>

  <Step title="Avoid Unnecessary Requests">
    Plan queries carefully to minimize redundant API calls
  </Step>

  <Step title="Off-Peak Usage">
    Schedule heavy queries during off-peak hours
  </Step>
</Steps>

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Authentication Failed (401)">
    **Symptoms:** "Bad Request. The value for variable api\_key is not registered."

    **Solutions:**

    * Verify API key is correct (check for typos)
    * Ensure environment variable is set
    * Restart the MCP server after changing config
    * Check key hasn't been revoked
  </Accordion>

  <Accordion title="Rate Limited (429)">
    **Symptoms:** "Too many requests"

    **Solutions:**

    * Wait 60 seconds before retrying
    * Reduce request frequency
    * Use date ranges to limit data size
    * Use fewer concurrent requests
  </Accordion>

  <Accordion title="Environment Variable Not Found">
    **Symptoms:** Server starts but requests fail

    **Solutions:**

    * Check variable name is exactly `FRED_API_KEY`
    * Verify it's set in the correct profile file
    * Restart terminal/application after setting
    * Use absolute paths in configuration
  </Accordion>

  <Accordion title="Invalid Response Format">
    **Symptoms:** JSON parsing errors

    **Solutions:**

    * Verify API key format (32 hex characters)
    * Check for special characters in key
    * Ensure no whitespace in environment variable
  </Accordion>
</AccordionGroup>

### Debug Mode

Enable detailed logging:

```bash theme={null}
DEBUG=fred:* npx fred-mcp-server
```

This shows:

* Request URLs (with key redacted)
* Response status codes
* Rate limit status
* Error details

## Key Management

### Regenerating Keys

If your key is compromised:

<Steps>
  <Step title="Login to FRED Account">
    Visit your [API Keys page](https://fredaccount.stlouisfed.org/apikeys)
  </Step>

  <Step title="Revoke Old Key">
    Click "Delete" next to the compromised key
  </Step>

  <Step title="Generate New Key">
    Click "Request API Key" to create a replacement
  </Step>

  <Step title="Update Configuration">
    Replace the old key in all your configurations
  </Step>

  <Step title="Restart Services">
    Restart MCP server and any dependent applications
  </Step>
</Steps>

### Multiple Keys

You can have multiple API keys:

```json theme={null}
{
  "mcpServers": {
    "fred-dev": {
      "command": "npx",
      "args": ["-y", "fred-mcp-server"],
      "env": {
        "FRED_API_KEY": "development-key"
      }
    },
    "fred-prod": {
      "command": "npx",
      "args": ["-y", "fred-mcp-server"],
      "env": {
        "FRED_API_KEY": "production-key"
      }
    }
  }
}
```

## Terms of Use

By using the FRED API, you agree to:

<CardGroup>
  <Card title="Attribution" icon="quote-left">
    Credit Federal Reserve Bank of St. Louis and FRED
  </Card>

  <Card title="Non-Commercial" icon="hand-holding-dollar">
    Free for research, education, and personal use
  </Card>

  <Card title="No Resale" icon="ban">
    Don't redistribute raw data commercially
  </Card>

  <Card title="Respect Limits" icon="gauge-high">
    Adhere to rate limits and usage guidelines
  </Card>
</CardGroup>

<Info>
  For commercial use or higher limits, contact the [FRED team](mailto:stlsFRED@stls.frb.org) directly.
</Info>

## Next Steps

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Start using the MCP server
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/overview">
    Explore available tools
  </Card>

  <Card title="Examples" icon="code" href="/examples/basic-usage">
    See usage examples
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/resources/troubleshooting">
    Get help with issues
  </Card>
</CardGroup>


# FRED Data
Source: https://fred-mcp-server.amorelli.tech/core-concepts/fred-data

Understanding FRED's data structure and organization

# FRED Data Structure

FRED (Federal Reserve Economic Data) contains over 800,000 economic time series with a well-organized hierarchical structure.

## Data Hierarchy

```mermaid theme={null}
graph TD
    A[FRED Root] --> B[Categories]
    B --> C[Subcategories]
    C --> D[Series]
    D --> E[Observations]
    B --> F[Releases]
    F --> D
    D --> G[Tags]
```

## Core Entities

### Series

A series is a single economic indicator tracked over time.

<ParamField type="string">
  Unique identifier (e.g., "GDP", "UNRATE", "DFF")
</ParamField>

<ParamField type="string">
  Full descriptive name
</ParamField>

<ParamField type="date">
  Date of first available data point
</ParamField>

<ParamField type="date">
  Date of most recent data point
</ParamField>

<ParamField type="string">
  Data collection interval: Daily, Weekly, Monthly, Quarterly, Annual
</ParamField>

<ParamField type="string">
  Measurement units (Dollars, Percent, Index, etc.)
</ParamField>

<ParamField type="string">
  SA (Seasonally Adjusted), NSA (Not Seasonally Adjusted), SAAR
</ParamField>

<ParamField type="integer">
  Usage ranking from 1-100
</ParamField>

**Example Series:**

```json theme={null}
{
  "id": "UNRATE",
  "title": "Unemployment Rate",
  "observation_start": "1948-01-01",
  "observation_end": "2024-09-01",
  "frequency": "Monthly",
  "frequency_short": "M",
  "units": "Percent",
  "seasonal_adjustment": "Seasonally Adjusted",
  "popularity": 95,
  "notes": "The unemployment rate represents..."
}
```

### Observations

Individual data points within a series.

```json theme={null}
{
  "observations": [
    {
      "date": "2024-09-01",
      "value": "4.2",
      "realtime_start": "2024-10-04",
      "realtime_end": "2024-10-04"
    },
    {
      "date": "2024-08-01",
      "value": "4.3",
      "realtime_start": "2024-09-06",
      "realtime_end": "2024-09-06"
    }
  ]
}
```

### Categories

Hierarchical organization of related series.

<CardGroup>
  <Card title="Money, Banking & Finance" icon="dollar-sign">
    32991 - Interest rates, exchange rates, monetary aggregates
  </Card>

  <Card title="Population, Employment & Labor" icon="users">
    10 - Demographics, employment, wages
  </Card>

  <Card title="Production & Business Activity" icon="industry">
    1 - GDP, industrial production, capacity utilization
  </Card>

  <Card title="Prices" icon="tag">
    32455 - Inflation, CPI, PPI, import/export prices
  </Card>

  <Card title="International Data" icon="globe">
    32263 - Global economic indicators
  </Card>

  <Card title="U.S. Regional Data" icon="map">
    3008 - State and metro area statistics
  </Card>
</CardGroup>

### Releases

Scheduled data publications from source agencies.

```json theme={null}
{
  "id": 50,
  "realtime_start": "2024-10-01",
  "realtime_end": "2024-10-01",
  "name": "Employment Situation",
  "press_release": true,
  "link": "https://www.bls.gov/news.release/empsit.htm"
}
```

### Tags

Categorical descriptors for discovery and filtering.

**Tag Categories:**

* **Geographic**: usa, state, nation, county, msa
* **Frequency**: daily, weekly, monthly, quarterly, annual
* **Source**: bls, bea, census, frb, oecd
* **Topic**: employment, gdp, inflation, interest rate
* **Seasonal Adjustment**: sa, nsa, saar

## Data Types

### Economic Indicators

<Tabs>
  <Tab title="Labor Market">
    * Unemployment Rate (UNRATE)
    * Nonfarm Payrolls (PAYEMS)
    * Labor Force Participation (CIVPART)
    * Initial Jobless Claims (ICSA)
    * Average Hourly Earnings (CES0500000003)
  </Tab>

  <Tab title="Production">
    * Gross Domestic Product (GDP)
    * Industrial Production (INDPRO)
    * Capacity Utilization (TCU)
    * Manufacturing Output (IPMAN)
    * Retail Sales (RSXFS)
  </Tab>

  <Tab title="Prices">
    * Consumer Price Index (CPIAUCSL)
    * Core CPI (CPILFESL)
    * Producer Price Index (PPIACO)
    * PCE Price Index (PCEPI)
    * Import Price Index (IR)
  </Tab>

  <Tab title="Financial">
    * Federal Funds Rate (DFF)
    * 10-Year Treasury (DGS10)
    * S\&P 500 (SP500)
    * Exchange Rates (DEXUSEU)
    * M2 Money Supply (M2SL)
  </Tab>
</Tabs>

### Frequency Types

| Frequency  | Code | Typical Use Cases          | Example                |
| ---------- | ---- | -------------------------- | ---------------------- |
| Daily      | d    | Financial markets, rates   | Fed Funds Rate         |
| Weekly     | w    | Claims, surveys            | Initial Claims         |
| Biweekly   | bw   | Specific surveys           | Retail sales surveys   |
| Monthly    | m    | Most indicators            | Unemployment, CPI      |
| Quarterly  | q    | GDP, accounts              | GDP, Corporate Profits |
| Semiannual | sa   | Some surveys               | Business outlook       |
| Annual     | a    | Demographics, some surveys | Population             |

### Units and Scaling

<Warning>
  **Critical: Always check units and scaling**

  Values may be expressed as:

  * Raw numbers (e.g., persons employed)
  * Thousands or millions (e.g., GDP in billions)
  * Index values (e.g., CPI with base year)
  * Percentages (e.g., unemployment rate)
  * Rates (e.g., annual rate)
</Warning>

Common unit types:

```json theme={null}
{
  "units": "Billions of Dollars",
  "units": "Percent",
  "units": "Index 1982-1984=100",
  "units": "Thousands of Persons",
  "units": "Index 2012=100",
  "units": "Millions of Dollars"
}
```

## Data Transformations

### Available Transformations

| Transformation                 | Code | Formula                   | Use Case                |
| ------------------------------ | ---- | ------------------------- | ----------------------- |
| Levels                         | lin  | Raw value                 | Actual amounts          |
| Change                         | chg  | x\_t - x\_                | Period-to-period change |
| Change from Year Ago           | ch1  | x\_t - x\_                | Annual change           |
| Percent Change                 | pch  | ((x\_t/x\_)-1)\*100       | Growth rates            |
| Percent Change from Year Ago   | pc1  | ((x\_t/x\_)-1)\*100       | Annual growth           |
| Compounded Annual Rate         | pca  | (((x\_t/x\_)^(n))-1)\*100 | Annualized growth       |
| Continuously Compounded Rate   | cch  | (ln(x\_t)-ln(x\_))\*100   | Log returns             |
| Continuously Compounded Annual | cca  | (ln(x\_t)-ln(x\_))\*100   | Log annual returns      |
| Natural Log                    | log  | ln(x\_t)                  | Statistical analysis    |

### Aggregation Methods

When converting frequency:

| Method        | Description     | Best For                            |
| ------------- | --------------- | ----------------------------------- |
| Average       | Mean of period  | Flow variables (rates, prices)      |
| Sum           | Total of period | Stock variables (production, sales) |
| End of Period | Last value      | Levels, indices                     |

## Data Quality

### Revisions

Economic data undergoes revisions:

<Steps>
  <Step title="Preliminary Release">
    Initial estimate based on partial data
  </Step>

  <Step title="Revised Release">
    Updated with more complete information
  </Step>

  <Step title="Final Release">
    Comprehensive data, may come months later
  </Step>

  <Step title="Annual Revisions">
    Methodological updates and rebasing
  </Step>
</Steps>

### Vintage Data

FRED maintains historical snapshots:

```json theme={null}
{
  "realtime_start": "2024-01-05",
  "realtime_end": "2024-01-05",
  "observation_start": "2023-12-01",
  "observation_end": "2023-12-01",
  "vintage_dates": [
    "2024-01-05",
    "2023-12-08",
    "2023-11-03"
  ]
}
```

This allows analysis of:

* Data as it was known at specific dates
* Magnitude of revisions
* Forecasting accuracy

### Missing Values

Series may have gaps:

* Discontinued series
* Weekends/holidays (daily data)
* Not-yet-released observations
* Suppressed values (privacy/reliability)

Represented as:

```json theme={null}
{
  "date": "2024-01-01",
  "value": "."
}
```

## Search and Discovery

### Full-Text Search

Search across:

* Series titles
* Series descriptions
* Category names
* Tag names
* Release names

**Example:**

```
"unemployment" → Returns ~500 series
"unemployment rate seasonally adjusted" → ~50 series
"UNRATE" → Exact match
```

### Tag-Based Filtering

Combine multiple tags:

```
tags: ["monthly", "sa", "bls", "employment"]
```

### Category Browsing

Navigate hierarchy:

```
Root (0)
  └─ Population, Employment & Labor Markets (10)
      └─ Current Employment Statistics (11)
          └─ [~500 series]
```

## Common Series

### Key Economic Indicators

<AccordionGroup>
  <Accordion title="Labor Market (Monthly)">
    * **UNRATE**: Unemployment Rate (SA)
    * **PAYEMS**: Total Nonfarm Payrolls (SA)
    * **CIVPART**: Labor Force Participation Rate (SA)
    * **U6RATE**: Total Unemployed + Marginally Attached (SA)
  </Accordion>

  <Accordion title="GDP & Production (Quarterly)">
    * **GDP**: Gross Domestic Product (SAAR)
    * **GDPC1**: Real GDP (SAAR)
    * **INDPRO**: Industrial Production Index (SA)
    * **TCU**: Capacity Utilization (SA)
  </Accordion>

  <Accordion title="Inflation (Monthly)">
    * **CPIAUCSL**: CPI All Items (SA)
    * **CPILFESL**: CPI Less Food & Energy (SA)
    * **PCEPI**: PCE Price Index (SA)
    * **PCEPILFE**: Core PCE Price Index (SA)
  </Accordion>

  <Accordion title="Interest Rates (Daily)">
    * **DFF**: Federal Funds Effective Rate
    * **DGS10**: 10-Year Treasury Constant Maturity
    * **DGS2**: 2-Year Treasury Constant Maturity
    * **T10Y2Y**: 10-Year minus 2-Year Treasury Spread
  </Accordion>
</AccordionGroup>

## API Response Format

### Series Metadata

```json theme={null}
{
  "seriess": [{
    "id": "GDP",
    "realtime_start": "2024-10-01",
    "realtime_end": "2024-10-01",
    "title": "Gross Domestic Product",
    "observation_start": "1947-01-01",
    "observation_end": "2024-04-01",
    "frequency": "Quarterly",
    "frequency_short": "Q",
    "units": "Billions of Dollars",
    "units_short": "Bil. of $",
    "seasonal_adjustment": "Seasonally Adjusted Annual Rate",
    "seasonal_adjustment_short": "SAAR",
    "last_updated": "2024-09-26 07:46:02-05",
    "popularity": 92,
    "notes": "BEA Account Code: A191RC..."
  }]
}
```

### Observations Data

```json theme={null}
{
  "realtime_start": "2024-10-01",
  "realtime_end": "2024-10-01",
  "observation_start": "2020-01-01",
  "observation_end": "2024-04-01",
  "units": "lin",
  "output_type": 1,
  "file_type": "json",
  "order_by": "observation_date",
  "sort_order": "asc",
  "count": 18,
  "offset": 0,
  "limit": 100000,
  "observations": [...]
}
```

## Next Steps

<CardGroup>
  <Card title="API Tools" icon="wrench" href="/api-reference/overview">
    Use data retrieval tools
  </Card>

  <Card title="Examples" icon="code" href="/examples/basic-usage">
    See practical examples
  </Card>

  <Card title="Common Series" icon="chart-line" href="/resources/common-series">
    Popular indicators
  </Card>

  <Card title="Transformations" icon="calculator" href="/resources/data-transformations">
    Data transformation guide
  </Card>
</CardGroup>


# MCP Protocol
Source: https://fred-mcp-server.amorelli.tech/core-concepts/mcp-protocol

Understanding the Model Context Protocol

# Model Context Protocol (MCP)

The Model Context Protocol is an open standard that enables AI assistants to securely connect to external data sources and tools.

## Protocol Overview

MCP provides a standardized way for AI assistants to:

<CardGroup>
  <Card title="Access Tools" icon="wrench">
    Execute functions and retrieve data from external systems
  </Card>

  <Card title="Exchange Data" icon="arrow-right-arrow-left">
    Send structured requests and receive formatted responses
  </Card>

  <Card title="Maintain Context" icon="brain">
    Preserve conversation state and execution history
  </Card>

  <Card title="Ensure Security" icon="shield">
    Control access and validate requests
  </Card>
</CardGroup>

## Architecture

### Communication Flow

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Client as MCP Client
    participant Server as MCP Server
    participant API as External API

    User->>Client: Request data
    Client->>Server: MCP tool request
    Server->>API: API call
    API->>Server: API response
    Server->>Client: MCP formatted response
    Client->>User: Present results
```

### Components

#### MCP Client

The client runs within the AI assistant environment:

* Handles user interactions
* Formats tool requests according to MCP spec
* Parses server responses
* Manages connection lifecycle

#### MCP Server

The server bridges AI assistants and external services:

* Exposes available tools and capabilities
* Validates incoming requests
* Transforms requests to API calls
* Formats responses for AI consumption
* Handles errors and retries

## Protocol Features

### Tool Discovery

Servers advertise their capabilities:

```json theme={null}
{
  "tools": [
    {
      "name": "fred_search",
      "description": "Search FRED economic data series",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Search terms"
          }
        },
        "required": ["query"]
      }
    }
  ]
}
```

### Request Format

Tool calls follow a standardized structure:

```json theme={null}
{
  "method": "tools/call",
  "params": {
    "name": "fred_search",
    "arguments": {
      "query": "unemployment rate",
      "limit": 10
    }
  }
}
```

### Response Format

Servers return structured data:

```json theme={null}
{
  "content": [
    {
      "type": "text",
      "text": "Found 10 series matching query"
    },
    {
      "type": "resource",
      "resource": {
        "uri": "fred://series/UNRATE",
        "name": "Unemployment Rate",
        "mimeType": "application/json"
      }
    }
  ]
}
```

## Connection Types

### Standard I/O (stdio)

Direct process communication:

* Server runs as subprocess
* Uses stdin/stdout for messaging
* Lowest latency
* Most secure (no network exposure)

**Configuration:**

```json theme={null}
{
  "mcpServers": {
    "fred": {
      "command": "npx",
      "args": ["-y", "fred-mcp-server"],
      "env": {
        "FRED_API_KEY": "your-api-key"
      }
    }
  }
}
```

### HTTP/SSE

Network-based communication:

* Server runs as web service
* Uses Server-Sent Events for streaming
* Supports remote deployment
* Requires network configuration

## Security Model

### Authentication

<AccordionGroup>
  <Accordion title="API Key Management">
    * Keys stored in environment variables
    * Never exposed in requests/responses
    * Can be rotated without code changes
  </Accordion>

  <Accordion title="Request Validation">
    * Schema validation on all inputs
    * Type checking and sanitization
    * Rate limiting enforcement
  </Accordion>

  <Accordion title="Sandboxing">
    * Server runs in isolated process
    * Limited filesystem access
    * Network access controlled
  </Accordion>
</AccordionGroup>

### Data Privacy

MCP ensures:

* No data logged without consent
* Responses contain only requested data
* Secure transmission between components
* API keys never appear in responses

## Error Handling

### Error Types

| Code   | Type             | Description                 |
| ------ | ---------------- | --------------------------- |
| -32700 | Parse Error      | Invalid JSON received       |
| -32600 | Invalid Request  | Malformed request structure |
| -32601 | Method Not Found | Unknown tool requested      |
| -32602 | Invalid Params   | Bad parameter values        |
| -32603 | Internal Error   | Server-side failure         |

### Error Response Format

```json theme={null}
{
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "field": "query",
      "reason": "Required parameter missing"
    }
  }
}
```

## Performance Considerations

### Request Optimization

<Steps>
  <Step title="Batch Related Calls">
    Group similar requests when possible
  </Step>

  <Step title="Use Streaming">
    For large datasets, stream results incrementally
  </Step>

  <Step title="Limit Data Requests">
    Request only necessary date ranges and series
  </Step>

  <Step title="Implement Timeouts">
    Set reasonable limits for long-running operations
  </Step>
</Steps>

### Connection Management

* Reuse server processes
* Implement connection pooling
* Handle graceful shutdowns
* Monitor resource usage

## MCP Specification

The protocol follows JSON-RPC 2.0 with extensions:

### Core Methods

| Method           | Purpose                  |
| ---------------- | ------------------------ |
| `initialize`     | Establish connection     |
| `tools/list`     | Discover available tools |
| `tools/call`     | Execute tool             |
| `resources/list` | List available resources |
| `resources/read` | Access resource content  |
| `prompts/list`   | Get prompt templates     |

### Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> Initializing
    Initializing --> Ready: initialize success
    Ready --> ToolCall: tools/call
    ToolCall --> Ready: response
    Ready --> [*]: shutdown
```

## Best Practices

### Server Development

<Tip>
  **Key principles:**

  * Implement comprehensive error handling
  * Validate all inputs thoroughly
  * Provide clear, descriptive tool schemas
  * Return actionable error messages
  * Log appropriately for debugging
</Tip>

### Client Integration

<Warning>
  **Common pitfalls:**

  * Not handling connection failures
  * Ignoring timeout scenarios
  * Poor error message presentation
  * Inadequate retry logic
</Warning>

## FRED MCP Implementation

This server implements MCP to provide:

### Tools

1. **fred\_search**: Full-text search across all series
2. **fred\_browse**: Navigate category hierarchy
3. **fred\_get\_series**: Retrieve time series data

### Resources

* Series metadata
* Category information
* Release schedules

### Prompts

* Economic analysis templates
* Data exploration guides
* Research question frameworks

## Next Steps

<CardGroup>
  <Card title="API Tools" icon="wrench" href="/api-reference/overview">
    Explore available tools
  </Card>

  <Card title="FRED Data" icon="database" href="/core-concepts/fred-data">
    Understand data structure
  </Card>

  <Card title="Authentication" icon="key" href="/core-concepts/authentication">
    Setup API access
  </Card>

  <Card title="Examples" icon="code" href="/examples/basic-usage">
    See usage examples
  </Card>
</CardGroup>


# Overview
Source: https://fred-mcp-server.amorelli.tech/core-concepts/overview

Core concepts of the FRED MCP Server

# Core Concepts

Understanding the fundamental concepts behind the FRED MCP Server will help you use it effectively.

## What is FRED?

**FRED (Federal Reserve Economic Data)** is a comprehensive database maintained by the Federal Reserve Bank of St. Louis containing over 800,000 economic time series from 100+ sources.

### Key Features

<CardGroup>
  <Card title="Comprehensive Coverage" icon="globe">
    Data from U.S. government agencies, international organizations, and academic sources
  </Card>

  <Card title="Historical Depth" icon="clock-rotate-left">
    Some series dating back to the 1800s, providing long-term economic perspective
  </Card>

  <Card title="Real-Time Updates" icon="arrows-rotate">
    Data updated as soon as released by source agencies
  </Card>

  <Card title="Free Access" icon="unlock">
    All data freely available with API key registration
  </Card>
</CardGroup>

## What is MCP?

**Model Context Protocol (MCP)** is an open standard for connecting AI assistants to external data sources and tools.

### MCP Benefits

* **Standardized Interface**: Consistent way to access external tools
* **Security**: Controlled access to resources
* **Flexibility**: Works with any MCP-compatible client
* **Extensibility**: Easy to add new capabilities

## How FRED MCP Server Works

```mermaid theme={null}
graph LR
    A[AI Assistant] -->|MCP Protocol| B[FRED MCP Server]
    B -->|API Requests| C[FRED API]
    C -->|Economic Data| B
    B -->|Structured Response| A
    A -->|Analysis| D[User]
```

### Architecture Components

1. **MCP Client** (e.g., Claude Desktop)
   * Sends tool requests
   * Receives structured data
   * Presents results to user

2. **FRED MCP Server**
   * Translates MCP requests to FRED API calls
   * Handles authentication
   * Processes and formats responses
   * Manages rate limiting

3. **FRED API**
   * Official Federal Reserve data source
   * RESTful API endpoints
   * JSON/XML responses

## Data Organization

### Series Structure

Each FRED series has:

<ParamField type="string">
  Unique identifier (e.g., "GDP", "UNRATE")
</ParamField>

<ParamField type="string">
  Descriptive name
</ParamField>

<ParamField type="string">
  Data interval (daily, weekly, monthly, quarterly, annual)
</ParamField>

<ParamField type="string">
  Measurement units (percent, billions of dollars, index)
</ParamField>

<ParamField type="string">
  Whether data is seasonally adjusted
</ParamField>

<ParamField type="array">
  Time series data points with dates and values
</ParamField>

### Category Hierarchy

FRED organizes data in a hierarchical category structure:

```
Root Categories
├── Money, Banking & Finance
│   ├── Interest Rates
│   ├── Exchange Rates
│   └── Banking
├── Population, Employment & Labor Markets
│   ├── Unemployment Rate
│   ├── Employment
│   └── Labor Force
└── Production & Business Activity
    ├── GDP
    ├── Industrial Production
    └── Business Surveys
```

### Data Sources

Major data providers include:

* **U.S. Government Agencies**
  * Bureau of Labor Statistics (BLS)
  * Bureau of Economic Analysis (BEA)
  * Census Bureau
  * Federal Reserve Board

* **International Organizations**
  * World Bank
  * OECD
  * IMF
  * Bank for International Settlements

* **Academic Institutions**
  * University research centers
  * Economic research organizations

## Time Series Concepts

### Frequency

Data collection intervals:

| Frequency | Code | Example Series               |
| --------- | ---- | ---------------------------- |
| Daily     | d    | DFF (Fed Funds Rate)         |
| Weekly    | w    | ICSA (Initial Claims)        |
| Monthly   | m    | UNRATE (Unemployment)        |
| Quarterly | q    | GDP (Gross Domestic Product) |
| Annual    | a    | POPTHM (Population)          |

### Seasonal Adjustment

Many economic series show seasonal patterns:

* **SA (Seasonally Adjusted)**: Seasonal effects removed
* **NSA (Not Seasonally Adjusted)**: Raw data with seasonal patterns
* **SAAR (Seasonally Adjusted Annual Rate)**: Adjusted and annualized

### Transformations

Mathematical operations on data:

| Transform      | Code | Description              | Use Case             |
| -------------- | ---- | ------------------------ | -------------------- |
| Levels         | lin  | Raw values               | Actual amounts       |
| Change         | chg  | Difference from previous | Absolute changes     |
| Percent Change | pch  | % change from previous   | Growth rates         |
| Year-over-Year | pc1  | % change from year ago   | Annual comparisons   |
| Log            | log  | Natural logarithm        | Statistical analysis |

## Data Quality

### Vintage Data

FRED maintains historical versions of data:

* **Real-time data**: Current values
* **Vintage data**: Values as they existed on specific dates
* **Revisions**: Updates to previously released data

### Data Updates

Update patterns vary by series:

* **High-frequency**: Updated daily or weekly
* **Monthly indicators**: Released on schedule (e.g., first Friday)
* **Quarterly data**: Released with lag (e.g., GDP one month after quarter end)
* **Annual series**: Updated yearly

### Missing Data

Handling gaps in series:

* Some series have incomplete histories
* Holidays and weekends create gaps in daily data
* Series may be discontinued or replaced

## API Concepts

### Rate Limiting

FRED API has usage limits:

* **120 requests/minute**: General limit
* **40 requests/minute**: For series observations
* **Daily limit**: Varies by API key tier

The MCP server handles this automatically with:

* Request queuing
* Exponential backoff
* Retry logic

### Pagination

Large result sets use pagination:

```json theme={null}
{
  "limit": 100,    // Items per page
  "offset": 200,   // Skip first 200 items
  "total": 1500    // Total available items
}
```

### Error Handling

Common error types:

| Code | Meaning      | Resolution       |
| ---- | ------------ | ---------------- |
| 400  | Bad Request  | Check parameters |
| 401  | Unauthorized | Verify API key   |
| 404  | Not Found    | Check series ID  |
| 429  | Rate Limited | Wait and retry   |
| 500  | Server Error | Retry later      |

## Search and Discovery

### Search Methods

1. **Text Search**: Find series by keywords
2. **Tag Search**: Filter by categories and attributes
3. **Browse**: Navigate category hierarchy
4. **Release-based**: Find series by data release

### Tag System

Tags categorize and describe series:

* **Geographic**: usa, state, county, msa
* **Frequency**: daily, weekly, monthly
* **Topic**: gdp, inflation, employment
* **Source**: bls, bea, federal reserve

### Popularity Ranking

FRED tracks series popularity:

* Based on access frequency
* Helps identify commonly-used indicators
* Range from 1-100

## Best Practices

### Efficient Queries

<Steps>
  <Step title="Use Specific IDs">
    When you know the series ID, use it directly
  </Step>

  <Step title="Limit Date Ranges">
    Request only the time period you need
  </Step>

  <Step title="Plan Queries Carefully">
    Think through data needs to avoid redundant requests
  </Step>

  <Step title="Batch Related Requests">
    Group similar queries to minimize API calls
  </Step>
</Steps>

### Data Interpretation

<Warning>
  **Important considerations:**

  * Check units and scaling (millions vs billions)
  * Verify seasonal adjustment status
  * Note data frequency and aggregation
  * Consider revision history for critical analysis
</Warning>

## Common Patterns

### Economic Analysis Pattern

1. **Discover** relevant series using search/browse
2. **Retrieve** data with appropriate transformations
3. **Compare** across time periods or series
4. **Analyze** trends and relationships

### Monitoring Pattern

1. **Identify** key indicators to track
2. **Schedule** regular data retrieval
3. **Alert** on significant changes
4. **Report** findings

### Research Pattern

1. **Browse** categories for comprehensive coverage
2. **Search** for specific relationships
3. **Retrieve** long historical periods
4. **Transform** for statistical analysis

## Next Steps

<CardGroup>
  <Card title="MCP Protocol" icon="plug" href="/core-concepts/mcp-protocol">
    Learn about MCP architecture
  </Card>

  <Card title="FRED Data" icon="database" href="/core-concepts/fred-data">
    Explore FRED data structure
  </Card>

  <Card title="Authentication" icon="key" href="/core-concepts/authentication">
    API key and security
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Tool documentation
  </Card>
</CardGroup>


# Advanced Queries
Source: https://fred-mcp-server.amorelli.tech/examples/advanced-queries

Complex search patterns and data retrieval strategies

# Advanced Queries

Master complex search patterns, filtering techniques, and efficient data retrieval strategies using the FRED MCP Server.

## Advanced Search

### Multi-term Search

Combine multiple keywords:

```javascript theme={null}
{
  "query": "unemployment rate seasonally adjusted",
  "limit": 20,
  "sort_by": "popularity"
}
```

**Search strategies:**

* More specific terms = fewer, more relevant results
* Include seasonal adjustment status
* Add frequency (monthly, quarterly)
* Specify geographic scope (national, state)

### Wildcard Patterns

Use partial series IDs:

```javascript theme={null}
{
  "query": "UNRATE*",
  "search_type": "series_id"
}
```

Returns:

* UNRATE (National)
* UNRATENSA (Not seasonally adjusted)
* UNRATEUSA (Alternate series)

### Source-Specific Searches

Find series from specific agencies:

<Tabs>
  <Tab title="Bureau of Labor Statistics">
    ```javascript theme={null}
    {
      "query": "employment",
      "tags": ["bls"],
      "limit": 50
    }
    ```
  </Tab>

  <Tab title="Bureau of Economic Analysis">
    ```javascript theme={null}
    {
      "query": "gdp",
      "tags": ["bea"],
      "limit": 50
    }
    ```
  </Tab>

  <Tab title="Federal Reserve Board">
    ```javascript theme={null}
    {
      "query": "interest rate",
      "tags": ["frb"],
      "limit": 50
    }
    ```
  </Tab>

  <Tab title="Census Bureau">
    ```javascript theme={null}
    {
      "query": "housing",
      "tags": ["census"],
      "limit": 50
    }
    ```
  </Tab>
</Tabs>

## Tag-Based Filtering

### Multiple Tag Combinations

```javascript theme={null}
{
  "query": "inflation",
  "tags": ["monthly", "sa", "usa"],
  "tag_mode": "all"  // Must match all tags
}
```

**Common tag combinations:**

<CardGroup>
  <Card title="National Monthly SA" icon="flag-usa">
    ```javascript theme={null}
    ["monthly", "sa", "usa"]
    ```
  </Card>

  <Card title="Quarterly National Accounts" icon="landmark">
    ```javascript theme={null}
    ["quarterly", "bea", "nipa"]
    ```
  </Card>

  <Card title="Daily Financial Data" icon="chart-candlestick">
    ```javascript theme={null}
    ["daily", "finance", "rates"]
    ```
  </Card>

  <Card title="State-Level Data" icon="map">
    ```javascript theme={null}
    ["state", "monthly", "sa"]
    ```
  </Card>
</CardGroup>

### Tag Discovery

Find related tags:

```javascript theme={null}
{
  "query": "employment",
  "include_observation_values": false,
  "sort_by": "popularity"
}
```

Then examine tags in results to refine search.

## Category-Based Browsing

### Navigate Hierarchy

<Steps>
  <Step title="Start at Root">
    ```javascript theme={null}
    {
      "category_id": 0
    }
    ```

    Returns top-level categories
  </Step>

  <Step title="Drill Down">
    ```javascript theme={null}
    {
      "category_id": 10  // Employment & Labor
    }
    ```

    Returns subcategories
  </Step>

  <Step title="Get Series">
    ```javascript theme={null}
    {
      "category_id": 11,  // Current Employment Statistics
      "limit": 100
    }
    ```

    Returns series in category
  </Step>
</Steps>

### Popular Categories

| Category ID | Name                           | Series Count |
| ----------- | ------------------------------ | ------------ |
| 32991       | Money, Banking & Finance       | \~10,000     |
| 10          | Population, Employment & Labor | \~15,000     |
| 1           | Production & Business Activity | \~40,000     |
| 32455       | Prices                         | \~25,000     |
| 32263       | International Data             | \~60,000     |
| 3008        | U.S. Regional Data             | \~30,000     |

## Geographic Queries

### State-Level Data

Find data for specific states:

```javascript theme={null}
{
  "query": "unemployment rate",
  "tags": ["state", "monthly", "sa"],
  "limit": 50
}
```

**State code patterns:**

* Format: `{INDICATOR}{STATE}`
* Example: `CAUR` (California Unemployment Rate)

<AccordionGroup>
  <Accordion title="California Data">
    ```javascript theme={null}
    // Unemployment
    { "series_id": "CAUR" }

    // GDP
    { "series_id": "CANGSP" }

    // Home Price Index
    { "series_id": "CASTHPI" }
    ```
  </Accordion>

  <Accordion title="Texas Data">
    ```javascript theme={null}
    // Unemployment
    { "series_id": "TXUR" }

    // GDP
    { "series_id": "TXNGSP" }

    // Home Price Index
    { "series_id": "TXSTHPI" }
    ```
  </Accordion>

  <Accordion title="New York Data">
    ```javascript theme={null}
    // Unemployment
    { "series_id": "NYUR" }

    // GDP
    { "series_id": "NYNGSP" }

    // Home Price Index
    { "series_id": "NYSTHPI" }
    ```
  </Accordion>
</AccordionGroup>

### Metro Area Data

Metropolitan Statistical Areas (MSAs):

```javascript theme={null}
{
  "query": "unemployment rate",
  "tags": ["msa", "monthly"],
  "limit": 100
}
```

**Example MSAs:**

* **LAUMT064910**: Los Angeles-Long Beach-Anaheim
* **LAUMT364190**: New York-Newark-Jersey City
* **LAUMT121410**: Chicago-Naperville-Elgin

### International Data

```javascript theme={null}
{
  "query": "gdp",
  "tags": ["oecd"],
  "limit": 50
}

// Or specific countries
{
  "query": "gdp japan",
  "limit": 20
}
```

## Frequency-Specific Searches

### Daily Data

```javascript theme={null}
{
  "tags": ["daily"],
  "query": "interest rate",
  "limit": 20
}
```

**Common daily series:**

* Treasury yields (DGS2, DGS10, DGS30)
* Fed funds rate (DFF)
* Exchange rates (DEXUSEU, DEXJPUS)
* Stock indices (SP500, DJIA)

### High-Frequency Financial

```javascript theme={null}
{
  "tags": ["daily", "finance"],
  "sort_by": "popularity",
  "limit": 50
}
```

### Low-Frequency Data

Annual or less frequent:

```javascript theme={null}
{
  "tags": ["annual"],
  "query": "population",
  "limit": 30
}
```

## Date Range Optimization

### Recent Data Only

```javascript theme={null}
{
  "series_id": "GDP",
  "observation_start": "2020-Q1",
  "observation_end": "2024-Q3"
}
```

<Tip>
  Limiting date ranges reduces API payload size and improves performance
</Tip>

### Historical Analysis

Long-term series:

```javascript theme={null}
{
  "series_id": "CPIAUCSL",
  "observation_start": "1947-01-01",  // Series inception
  "observation_end": "2024-10-01"
}
```

### Rolling Windows

Get last N periods:

```javascript theme={null}
{
  "series_id": "UNRATE",
  "observation_start": "2023-01-01",  // Last ~20 months
  "sort_order": "desc",
  "limit": 20
}
```

## Complex Filtering

### Popularity Threshold

Focus on commonly-used series:

```javascript theme={null}
{
  "query": "gdp",
  "sort_by": "popularity",
  "limit": 100
}
```

Filter results where popularity > 50:

```javascript theme={null}
results.filter(series => series.popularity > 50)
```

### Frequency Filtering

Find only monthly series:

```javascript theme={null}
{
  "query": "inflation",
  "tags": ["monthly"]
}
```

### Seasonal Adjustment

Prefer seasonally adjusted:

```javascript theme={null}
{
  "query": "retail sales",
  "tags": ["sa"]  // Seasonally adjusted only
}
```

## Batch Retrieval

### Multiple Series

Retrieve related series efficiently:

```javascript theme={null}
const series_ids = [
  "UNRATE",    // Unemployment
  "CPIAUCSL",  // CPI
  "GDP",       // GDP
  "DFF",       // Fed Funds
  "SP500"      // Stock Market
];

// Request each
series_ids.forEach(id => {
  fred_get_series({
    series_id: id,
    observation_start: "2020-01-01"
  });
});
```

### Category Sweep

Get all series in a category:

```javascript theme={null}
{
  "category_id": 11,  // Current Employment Statistics
  "limit": 1000,      // Max per request
  "offset": 0
}

// If more than 1000, paginate:
// offset: 1000, 2000, 3000, etc.
```

## Search Optimization

### Precision vs Recall

<Tabs>
  <Tab title="High Precision">
    ```javascript theme={null}
    {
      "query": "UNRATE",  // Exact ID
      "search_type": "series_id"
    }
    ```

    Returns: 1 exact match
  </Tab>

  <Tab title="High Recall">
    ```javascript theme={null}
    {
      "query": "unemployment"  // Broad term
    }
    ```

    Returns: \~500 related series
  </Tab>

  <Tab title="Balanced">
    ```javascript theme={null}
    {
      "query": "unemployment rate monthly",
      "tags": ["sa", "usa"],
      "limit": 20
    }
    ```

    Returns: 20 most relevant
  </Tab>
</Tabs>

### Sort Strategies

<AccordionGroup>
  <Accordion title="By Popularity">
    ```javascript theme={null}
    { "sort_by": "popularity" }
    ```

    Best for: Finding commonly-used series
  </Accordion>

  <Accordion title="By Name">
    ```javascript theme={null}
    {
      "sort_by": "title",
      "sort_order": "asc"
    }
    ```

    Best for: Alphabetical browsing
  </Accordion>

  <Accordion title="By Date">
    ```javascript theme={null}
    {
      "sort_by": "last_updated",
      "sort_order": "desc"
    }
    ```

    Best for: Finding recently updated data
  </Accordion>

  <Accordion title="By Series ID">
    ```javascript theme={null}
    {
      "sort_by": "series_id",
      "sort_order": "asc"
    }
    ```

    Best for: Finding related series by ID pattern
  </Accordion>
</AccordionGroup>

## Real-World Query Patterns

### Economic Dashboard

Build a monitoring dashboard:

```javascript theme={null}
const dashboard_queries = [
  // Labor Market
  {
    series_ids: ["UNRATE", "PAYEMS", "CIVPART"],
    start: "2020-01-01",
    transform: "lin"
  },

  // Inflation
  {
    series_ids: ["CPIAUCSL", "CPILFESL", "PCEPI"],
    start: "2020-01-01",
    transform: "pc1"
  },

  // Growth
  {
    series_ids: ["GDP", "GDPC1", "INDPRO"],
    start: "2020-Q1",
    transform: "pca"
  },

  // Markets
  {
    series_ids: ["DFF", "DGS10", "SP500"],
    start: "2020-01-01",
    transform: "lin"
  }
];
```

### Comparative Analysis

Compare across geographies:

```javascript theme={null}
const states = ["CA", "TX", "NY", "FL"];
const indicator = "UR";  // Unemployment Rate

states.forEach(state => {
  fred_get_series({
    series_id: `${state}${indicator}`,
    observation_start: "2020-01-01"
  });
});
```

### Historical Research

Long-term trend analysis:

```javascript theme={null}
{
  "series_id": "CPIAUCSL",
  "observation_start": "1947-01-01",  // Full history
  "units": "pc1",  // Annual inflation
  "frequency": "a",  // Annual frequency
  "aggregation_method": "eop"  // End of period
}
```

### Nowcasting

Get most recent values:

```javascript theme={null}
{
  "series_id": "UNRATE",
  "sort_order": "desc",
  "limit": 1  // Just the latest
}
```

## Performance Tips

<Steps>
  <Step title="Use Specific IDs">
    When known, use exact series IDs instead of search
  </Step>

  <Step title="Limit Date Ranges">
    Request only needed time periods
  </Step>

  <Step title="Apply Filters Early">
    Use tags to narrow before searching
  </Step>

  <Step title="Plan Data Needs">
    Identify what data you need upfront to avoid redundant calls
  </Step>

  <Step title="Batch Related Queries">
    Group similar requests together
  </Step>
</Steps>

## Troubleshooting

<Warning>
  **Common issues:**

  * **No results**: Query too specific, try broader terms
  * **Too many results**: Add tags or more specific terms
  * **Slow queries**: Reduce date range or result limit
  * **Unexpected series**: Check tags and sort order
</Warning>

### Query Refinement

```javascript theme={null}
// Too broad (10,000 results)
{ "query": "rate" }

// Better (500 results)
{ "query": "interest rate" }

// Best (20 results)
{
  "query": "interest rate",
  "tags": ["daily", "treasury"],
  "limit": 20
}
```

## Next Steps

<CardGroup>
  <Card title="API Reference" icon="book" href="/api-reference/overview">
    Complete tool documentation
  </Card>

  <Card title="Economic Analysis" icon="chart-mixed" href="/use-cases/economic-analysis">
    Applied analysis patterns
  </Card>

  <Card title="Common Series" icon="bookmark" href="/resources/common-series">
    Popular series reference
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/resources/troubleshooting">
    Solve common issues
  </Card>
</CardGroup>


# Basic Usage
Source: https://fred-mcp-server.amorelli.tech/examples/basic-usage

Getting started with common FRED MCP Server queries

# 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:

1. Configured your FRED API key
2. Connected the server to your MCP client
3. Verified the connection is working

## Common Economic Queries

### Unemployment Rate

<Tabs>
  <Tab title="Current Rate">
    **Query:** "What's the current US unemployment rate?"

    ```json theme={null}
    {
      "tool": "fred_get_series",
      "params": {
        "series_id": "UNRATE",
        "limit": 1,
        "sort_order": "desc"
      }
    }
    ```

    **Response:** Latest unemployment rate value
  </Tab>

  <Tab title="Last Year">
    **Query:** "Show unemployment rate for the last 12 months"

    ```json theme={null}
    {
      "tool": "fred_get_series",
      "params": {
        "series_id": "UNRATE",
        "limit": 12,
        "sort_order": "desc"
      }
    }
    ```

    **Response:** Monthly unemployment values
  </Tab>

  <Tab title="Historical Trend">
    **Query:** "Get unemployment trend since 2020"

    ```json theme={null}
    {
      "tool": "fred_get_series",
      "params": {
        "series_id": "UNRATE",
        "observation_start": "2020-01-01"
      }
    }
    ```

    **Response:** Full pandemic-era unemployment data
  </Tab>
</Tabs>

### Inflation Tracking

<Tabs>
  <Tab title="Current Inflation">
    **Query:** "What's the current inflation rate?"

    ```json theme={null}
    {
      "tool": "fred_get_series",
      "params": {
        "series_id": "CPIAUCSL",
        "units": "pc1",
        "limit": 1,
        "sort_order": "desc"
      }
    }
    ```

    **Response:** Year-over-year CPI change
  </Tab>

  <Tab title="Core vs Headline">
    **Query:** "Compare core and headline inflation"

    ```json theme={null}
    // 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
      }
    }
    ```
  </Tab>

  <Tab title="Monthly Changes">
    **Query:** "Show month-to-month inflation changes"

    ```json theme={null}
    {
      "tool": "fred_get_series",
      "params": {
        "series_id": "CPIAUCSL",
        "units": "pch",
        "limit": 12
      }
    }
    ```

    **Response:** Monthly percent changes
  </Tab>
</Tabs>

### GDP and Growth

<Tabs>
  <Tab title="Latest GDP">
    **Query:** "What's the latest GDP figure?"

    ```json theme={null}
    {
      "tool": "fred_get_series",
      "params": {
        "series_id": "GDP",
        "limit": 1,
        "sort_order": "desc"
      }
    }
    ```

    **Response:** Nominal GDP in billions
  </Tab>

  <Tab title="Real GDP Growth">
    **Query:** "Show real GDP growth rate"

    ```json theme={null}
    {
      "tool": "fred_get_series",
      "params": {
        "series_id": "GDPC1",
        "units": "pca",
        "limit": 8
      }
    }
    ```

    **Response:** Annualized growth rates
  </Tab>

  <Tab title="GDP Components">
    **Query:** "Break down GDP by components"

    ```json theme={null}
    // 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
    }
    ```
  </Tab>
</Tabs>

## Interest Rates

### Federal Reserve Rates

<CodeGroup>
  ```json Federal Funds Rate theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "DFF",
      "limit": 30
    }
  }
  ```

  ```json Target Rate Range theme={null}
  // Upper bound
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "DFEDTARU",
      "limit": 12
    }
  }

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

  ```json Real Interest Rate theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "REAINTRATREARAT10Y",
      "limit": 12
    }
  }
  ```
</CodeGroup>

### Treasury Yields

<CodeGroup>
  ```json Yield Curve theme={null}
  // 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}
  ```

  ```json Yield Spread theme={null}
  // 10Y-2Y Spread (Recession Indicator)
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "T10Y2Y",
      "limit": 252
    }
  }
  ```
</CodeGroup>

## Labor Market Data

### Employment Statistics

<CodeGroup>
  ```json Nonfarm Payrolls theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "PAYEMS",
      "units": "chg",
      "limit": 12
    }
  }
  ```

  ```json Labor Force Participation theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "CIVPART",
      "limit": 24
    }
  }
  ```

  ```json Average Hourly Earnings theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "CES0500000003",
      "units": "pc1",
      "limit": 12
    }
  }
  ```
</CodeGroup>

### Jobless Claims

<CodeGroup>
  ```json Initial Claims theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "ICSA",
      "limit": 52
    }
  }
  ```

  ```json Continuing Claims theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "CCSA",
      "limit": 52
    }
  }
  ```

  ```json 4-Week Moving Average theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "IC4WSA",
      "limit": 52
    }
  }
  ```
</CodeGroup>

## Housing Market

### Home Prices and Sales

<CodeGroup>
  ```json Case-Shiller Index theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "CSUSHPISA",
      "units": "pc1",
      "limit": 24
    }
  }
  ```

  ```json New Home Sales theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "HSN1F",
      "limit": 12
    }
  }
  ```

  ```json Housing Starts theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "HOUST",
      "limit": 12
    }
  }
  ```
</CodeGroup>

### Mortgage Rates

<CodeGroup>
  ```json 30-Year Fixed theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "MORTGAGE30US",
      "limit": 52
    }
  }
  ```

  ```json 15-Year Fixed theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "MORTGAGE15US",
      "limit": 52
    }
  }
  ```
</CodeGroup>

## Financial Markets

### Stock Market Indices

<CodeGroup>
  ```json S&P 500 theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "SP500",
      "limit": 252
    }
  }
  ```

  ```json NASDAQ theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "NASDAQCOM",
      "limit": 252
    }
  }
  ```

  ```json VIX Volatility theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "VIXCLS",
      "limit": 252
    }
  }
  ```
</CodeGroup>

### Exchange Rates

<CodeGroup>
  ```json EUR/USD theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "DEXUSEU",
      "limit": 30
    }
  }
  ```

  ```json USD/JPY theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "DEXJPUS",
      "limit": 30
    }
  }
  ```

  ```json Trade-Weighted Dollar theme={null}
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "DTWEXBGS",
      "limit": 52
    }
  }
  ```
</CodeGroup>

## Discovering Data

### Search for Series

<CodeGroup>
  ```json Find Inflation Indicators theme={null}
  {
    "tool": "fred_search",
    "params": {
      "search_text": "inflation",
      "tag_names": "usa,monthly",
      "limit": 10
    }
  }
  ```

  ```json Find State Data theme={null}
  {
    "tool": "fred_search",
    "params": {
      "search_text": "unemployment",
      "tag_names": "state,monthly,sa",
      "limit": 20
    }
  }
  ```

  ```json Find Recession Indicators theme={null}
  {
    "tool": "fred_search",
    "params": {
      "search_text": "recession",
      "order_by": "popularity",
      "limit": 10
    }
  }
  ```
</CodeGroup>

### Browse Categories

<CodeGroup>
  ```json Explore Main Categories theme={null}
  {
    "tool": "fred_browse",
    "params": {
      "browse_type": "categories"
    }
  }
  ```

  ```json Find Interest Rate Series theme={null}
  {
    "tool": "fred_browse",
    "params": {
      "browse_type": "category_series",
      "category_id": 22,
      "order_by": "popularity",
      "limit": 20
    }
  }
  ```

  ```json Browse Economic Releases theme={null}
  {
    "tool": "fred_browse",
    "params": {
      "browse_type": "releases",
      "order_by": "name",
      "limit": 30
    }
  }
  ```
</CodeGroup>

## Creating Reports

### Economic Dashboard

```javascript theme={null}
// 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

```javascript theme={null}
// 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

<Steps>
  <Step title="Start Simple">
    Begin with basic queries and add complexity as needed
  </Step>

  <Step title="Use Transformations">
    Apply units transformations for meaningful comparisons
  </Step>

  <Step title="Check Frequency">
    Ensure data frequencies match when comparing series
  </Step>

  <Step title="Handle Missing Data">
    Some series have gaps; always check for null values
  </Step>

  <Step title="Optimize Requests">
    Request only the data you need using limits and date ranges
  </Step>
</Steps>

## Common Patterns

### Latest Value Pattern

```json theme={null}
{
  "series_id": "SERIES_ID",
  "limit": 1,
  "sort_order": "desc"
}
```

### Time Period Pattern

```json theme={null}
{
  "series_id": "SERIES_ID",
  "observation_start": "START_DATE",
  "observation_end": "END_DATE"
}
```

### Growth Rate Pattern

```json theme={null}
{
  "series_id": "SERIES_ID",
  "units": "pc1",  // or "pch", "pca"
  "limit": 12
}
```

### Frequency Conversion Pattern

```json theme={null}
{
  "series_id": "SERIES_ID",
  "frequency": "m",  // or "q", "a"
  "aggregation_method": "avg"
}
```

## Next Steps

<CardGroup>
  <Card title="Economic Indicators" icon="chart-mixed" href="/examples/economic-indicators">
    Deep dive into key indicators
  </Card>

  <Card title="Time Series Analysis" icon="chart-line" href="/examples/time-series-analysis">
    Advanced analysis techniques
  </Card>

  <Card title="Data Transformations" icon="arrow-right-arrow-left" href="/examples/data-transformations">
    Master data transformations
  </Card>

  <Card title="Advanced Queries" icon="code" href="/examples/advanced-queries">
    Complex query patterns
  </Card>
</CardGroup>


# Data Transformations
Source: https://fred-mcp-server.amorelli.tech/examples/data-transformations

Transform economic data for analysis and comparison

# Data Transformations

FRED provides powerful transformation capabilities to prepare data for analysis. Learn how to apply transformations directly in your requests.

## Transformation Types

### Levels (lin)

Raw, untransformed data:

```javascript theme={null}
{
  "series_id": "GDP",
  "observation_start": "2020-Q1",
  "units": "lin"  // Default, can be omitted
}
```

**Output:**

```json theme={null}
[
  { "date": "2024-Q2", "value": "28647.8" },
  { "date": "2024-Q1", "value": "28435.1" }
]
```

<Note>
  Units: Billions of Dollars
</Note>

### Change (chg)

Absolute period-to-period change:

```javascript theme={null}
{
  "series_id": "GDP",
  "observation_start": "2020-Q1",
  "units": "chg"
}
```

**Formula:** `x_t - x_{t-1}`

**Output:**

```json theme={null}
[
  { "date": "2024-Q2", "value": "212.7" },
  { "date": "2024-Q1", "value": "157.3" }
]
```

**Use cases:**

* Quarterly GDP additions
* Monthly employment changes
* Period-over-period differences

### Percent Change (pch)

Period-to-period percentage change:

```javascript theme={null}
{
  "series_id": "GDP",
  "observation_start": "2020-Q1",
  "units": "pch"
}
```

**Formula:** `((x_t / x_{t-1}) - 1) * 100`

**Output:**

```json theme={null}
[
  { "date": "2024-Q2", "value": "0.75" },
  { "date": "2024-Q1", "value": "0.56" }
]
```

**Use cases:**

* Month-over-month inflation
* Quarter-over-quarter growth
* Short-term momentum

### Percent Change from Year Ago (pc1)

Year-over-year percentage change:

```javascript theme={null}
{
  "series_id": "CPIAUCSL",
  "observation_start": "2020-01-01",
  "units": "pc1"
}
```

**Formula:** `((x_t / x_{t-n}) - 1) * 100`

where `n` = periods in a year

**Output:**

```json theme={null}
[
  { "date": "2024-09-01", "value": "2.4" },
  { "date": "2024-08-01", "value": "2.5" }
]
```

**Use cases:**

* Annual inflation rates
* Year-over-year GDP growth
* Annual wage growth

<Tip>
  **pc1** is the most common transformation for inflation and growth rates
</Tip>

### Compounded Annual Rate of Change (pca)

Annualized growth rate:

```javascript theme={null}
{
  "series_id": "GDPC1",
  "observation_start": "2020-Q1",
  "units": "pca"
}
```

**Formula:** `(((x_t / x_{t-1})^(n)) - 1) * 100`

where `n` = periods per year

**Output:**

```json theme={null}
[
  { "date": "2024-Q2", "value": "3.0" },
  { "date": "2024-Q1", "value": "1.4" }
]
```

**Use cases:**

* Quarterly GDP at annual rates (official reporting)
* Annualizing monthly growth

<Warning>
  **pca** compounds the growth rate. A 0.75% quarterly growth becomes \~3% annual rate.
</Warning>

### Change from Year Ago (ch1)

Absolute change from same period last year:

```javascript theme={null}
{
  "series_id": "PAYEMS",
  "observation_start": "2020-01-01",
  "units": "ch1"
}
```

**Formula:** `x_t - x_{t-n}`

**Output:**

```json theme={null}
[
  { "date": "2024-09-01", "value": "2543" },
  { "date": "2024-08-01", "value": "2619" }
]
```

**Use cases:**

* Year-over-year job gains
* Annual change in levels

### Continuously Compounded Rate (cch)

Log difference (percentage):

```javascript theme={null}
{
  "series_id": "SP500",
  "observation_start": "2020-01-01",
  "units": "cch"
}
```

**Formula:** `(ln(x_t) - ln(x_{t-1})) * 100`

**Output:**

```json theme={null}
[
  { "date": "2024-10-25", "value": "0.52" },
  { "date": "2024-10-24", "value": "-0.18" }
]
```

**Use cases:**

* Financial returns analysis
* Statistical modeling
* Volatility calculations

### Continuously Compounded Annual Rate (cca)

Log difference annualized:

```javascript theme={null}
{
  "series_id": "GDP",
  "observation_start": "2020-Q1",
  "units": "cca"
}
```

**Formula:** `(ln(x_t) - ln(x_{t-n})) * 100`

**Use cases:**

* Academic research
* Econometric modeling

### Natural Log (log)

Logarithmic transformation:

```javascript theme={null}
{
  "series_id": "GDP",
  "observation_start": "2020-Q1",
  "units": "log"
}
```

**Formula:** `ln(x_t)`

**Output:**

```json theme={null}
[
  { "date": "2024-Q2", "value": "10.2627" },
  { "date": "2024-Q1", "value": "10.2553" }
]
```

**Use cases:**

* Identifying exponential trends
* Statistical analysis requiring normality
* Growth rate calculations

## Transformation Selection Guide

### By Use Case

<Tabs>
  <Tab title="Headlines & Reporting">
    ```javascript theme={null}
    // Year-over-year (most common for news)
    { "units": "pc1" }

    // Annualized rate (GDP reporting)
    { "units": "pca" }
    ```
  </Tab>

  <Tab title="Trend Analysis">
    ```javascript theme={null}
    // Original levels
    { "units": "lin" }

    // Log transformation for exponential trends
    { "units": "log" }
    ```
  </Tab>

  <Tab title="Momentum Analysis">
    ```javascript theme={null}
    // Month-over-month
    { "units": "pch" }

    // Absolute changes
    { "units": "chg" }
    ```
  </Tab>

  <Tab title="Statistical Analysis">
    ```javascript theme={null}
    // Log returns
    { "units": "cch" }

    // Log levels
    { "units": "log" }
    ```
  </Tab>
</Tabs>

### By Data Frequency

| Frequency | Common Transformations | Example               |
| --------- | ---------------------- | --------------------- |
| Daily     | lin, pch, cch          | Stock returns         |
| Weekly    | lin, pch, pc1          | Initial claims        |
| Monthly   | pc1, pch, ch1          | Inflation, employment |
| Quarterly | pca, pc1, log          | GDP growth            |
| Annual    | pc1, chg               | Demographics          |

## Practical Examples

### Inflation Analysis

<CodeGroup>
  ```javascript Month-over-Month theme={null}
  {
    "series_id": "CPIAUCSL",
    "units": "pch"
  }
  // Shows monthly price changes
  ```

  ```javascript Year-over-Year theme={null}
  {
    "series_id": "CPIAUCSL",
    "units": "pc1"
  }
  // Standard inflation reporting
  ```

  ```javascript Annualized Monthly theme={null}
  {
    "series_id": "CPIAUCSL",
    "units": "pca"
  }
  // Monthly change at annual rate
  ```
</CodeGroup>

### GDP Growth

<CodeGroup>
  ```javascript Quarter-over-Quarter theme={null}
  {
    "series_id": "GDPC1",
    "units": "pch"
  }
  // Simple quarterly growth
  ```

  ```javascript Annualized (Official) theme={null}
  {
    "series_id": "GDPC1",
    "units": "pca"
  }
  // BEA's official reporting method
  ```

  ```javascript Year-over-Year theme={null}
  {
    "series_id": "GDPC1",
    "units": "pc1"
  }
  // Annual comparison
  ```
</CodeGroup>

### Employment Changes

<CodeGroup>
  ```javascript Monthly Change theme={null}
  {
    "series_id": "PAYEMS",
    "units": "chg"
  }
  // Net jobs added/lost (in thousands)
  ```

  ```javascript Year-over-Year theme={null}
  {
    "series_id": "PAYEMS",
    "units": "ch1"
  }
  // Annual job growth (in thousands)
  ```

  ```javascript Growth Rate theme={null}
  {
    "series_id": "PAYEMS",
    "units": "pc1"
  }
  // Percentage employment growth
  ```
</CodeGroup>

## Combining Transformations

### Compare Multiple Views

```javascript theme={null}
// Original levels
const levels = {
  "series_id": "UNRATE",
  "observation_start": "2020-01-01",
  "units": "lin"
};

// Month-over-month change
const monthly = {
  "series_id": "UNRATE",
  "observation_start": "2020-01-01",
  "units": "chg"
};

// Year-over-year change
const annual = {
  "series_id": "UNRATE",
  "observation_start": "2020-01-01",
  "units": "ch1"
};
```

### Growth Decomposition

```javascript theme={null}
// Nominal GDP growth
const nominal = {
  "series_id": "GDP",
  "units": "pc1"
};

// Real GDP growth
const real = {
  "series_id": "GDPC1",
  "units": "pc1"
};

// Implicit: Price change ≈ Nominal - Real
```

## Advanced Techniques

### Detrending

Remove long-term trends using logs:

```javascript theme={null}
// Step 1: Get log values
{
  "series_id": "GDPC1",
  "observation_start": "2000-Q1",
  "units": "log"
}

// Step 2: Calculate deviations from trend
// (done in analysis tool)
```

### Volatility Measurement

Use continuous compounding for returns:

```javascript theme={null}
{
  "series_id": "SP500",
  "observation_start": "2023-01-01",
  "units": "cch"  // Daily log returns
}

// Calculate standard deviation for volatility
```

### Real vs Nominal

Deflate nominal series:

```javascript theme={null}
// Nominal wages
const nominal_wages = {
  "series_id": "CES0500000003"
};

// CPI (for deflation)
const cpi = {
  "series_id": "CPIAUCSL"
};

// Real wages = (Nominal / CPI) * 100
```

<Note>
  FRED often provides pre-calculated real series (look for "Real" in title)
</Note>

## Common Pitfalls

<AccordionGroup>
  <Accordion title="Mixing Frequencies">
    ❌ **Don't:** Compare monthly % change with quarterly

    ```javascript theme={null}
    { "series_id": "CPIAUCSL", "units": "pch" }  // Monthly
    { "series_id": "GDP", "units": "pch" }       // Quarterly
    ```

    ✅ **Do:** Use consistent frequencies

    ```javascript theme={null}
    { "series_id": "CPIAUCSL", "units": "pc1" }  // Annual
    { "series_id": "GDP", "units": "pc1" }       // Annual
    ```
  </Accordion>

  <Accordion title="Transformation on Transformations">
    ❌ **Don't:** Apply transformations to already-transformed series

    ```javascript theme={null}
    // Series ending in "CHG" or "PC1" are already transformed
    { "series_id": "GDPC1CHG", "units": "pch" }  // Wrong!
    ```

    ✅ **Do:** Use base series

    ```javascript theme={null}
    { "series_id": "GDPC1", "units": "pch" }  // Correct
    ```
  </Accordion>

  <Accordion title="Ignoring Units">
    ❌ **Don't:** Forget to check original units

    ```javascript theme={null}
    // Some series are in billions, others in thousands
    { "series_id": "GDP" }      // Billions
    { "series_id": "PAYEMS" }   // Thousands
    ```

    ✅ **Do:** Verify units in response
  </Accordion>

  <Accordion title="Seasonality Issues">
    ❌ **Don't:** Use NSA data for growth rates

    ```javascript theme={null}
    { "series_id": "UNRATENSA", "units": "pch" }  // Seasonal distortion
    ```

    ✅ **Do:** Use SA data for comparisons

    ```javascript theme={null}
    { "series_id": "UNRATE", "units": "pch" }  // Seasonally adjusted
    ```
  </Accordion>
</AccordionGroup>

## Transformation Reference

### Quick Reference Table

| Code | Name              | Formula                 | Period   | Use Case               |
| ---- | ----------------- | ----------------------- | -------- | ---------------------- |
| lin  | Levels            | x\_t                    | -        | Raw data               |
| chg  | Change            | x\_t - x\_              | Prior    | Absolute change        |
| ch1  | Change YoY        | x\_t - x\_              | Year ago | Annual absolute change |
| pch  | % Change          | ((x\_t/x\_)-1)\*100     | Prior    | Growth rate            |
| pc1  | % Change YoY      | ((x\_t/x\_)-1)\*100     | Year ago | Annual growth          |
| pca  | Compounded Annual | (((x\_t/x\_)^n)-1)\*100 | Annual   | Annualized rate        |
| cch  | Log Change        | (ln(x\_t)-ln(x\_))\*100 | Prior    | Log returns            |
| cca  | Log Change Annual | (ln(x\_t)-ln(x\_))\*100 | Annual   | Annual log returns     |
| log  | Natural Log       | ln(x\_t)                | -        | Log levels             |

### Frequency Multipliers (n)

| Frequency   | n (per year)                   |
| ----------- | ------------------------------ |
| Daily       | 365 (business) / 260 (trading) |
| Weekly      | 52                             |
| Monthly     | 12                             |
| Quarterly   | 4                              |
| Semi-annual | 2                              |
| Annual      | 1                              |

## Best Practices

<Steps>
  <Step title="Start with Levels">
    Always examine raw data first to understand scale and patterns
  </Step>

  <Step title="Match Use Case">
    Choose transformation based on your analysis needs
  </Step>

  <Step title="Document Choices">
    Note which transformations you applied for reproducibility
  </Step>

  <Step title="Verify Results">
    Sanity-check transformed values against known economic facts
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Time Series Analysis" icon="chart-line" href="/examples/time-series-analysis">
    Analyze transformed data
  </Card>

  <Card title="Advanced Queries" icon="magnifying-glass-chart" href="/examples/advanced-queries">
    Complex data retrieval
  </Card>

  <Card title="Economic Indicators" icon="chart-mixed" href="/examples/economic-indicators">
    Common indicator patterns
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/fred-get-series">
    Full transformation docs
  </Card>
</CardGroup>


# Economic Indicators
Source: https://fred-mcp-server.amorelli.tech/examples/economic-indicators

Working with key economic indicators using FRED MCP Server

# Economic Indicators Examples

Learn how to retrieve and analyze key economic indicators using the FRED MCP Server.

## Labor Market Indicators

### Unemployment Rate

Retrieve the monthly unemployment rate:

```javascript theme={null}
// Using fred_get_series
{
  "series_id": "UNRATE",
  "observation_start": "2020-01-01",
  "observation_end": "2024-10-01"
}
```

**Response:**

```json theme={null}
{
  "series_id": "UNRATE",
  "title": "Unemployment Rate",
  "units": "Percent",
  "frequency": "Monthly",
  "seasonal_adjustment": "Seasonally Adjusted",
  "observations": [
    {
      "date": "2024-09-01",
      "value": "4.2"
    },
    {
      "date": "2024-08-01",
      "value": "4.3"
    }
  ]
}
```

### Labor Force Participation

Track workforce participation trends:

```javascript theme={null}
{
  "series_id": "CIVPART",
  "observation_start": "2015-01-01"
}
```

<Tip>
  Combine multiple series to understand labor market dynamics:

  * **UNRATE**: Unemployment rate
  * **CIVPART**: Labor force participation
  * **EMRATIO**: Employment-population ratio
  * **U6RATE**: Broader unemployment measure
</Tip>

### Nonfarm Payrolls

Monthly employment changes:

```javascript theme={null}
{
  "series_id": "PAYEMS",
  "observation_start": "2023-01-01",
  "units": "chg",  // Period-to-period change
  "frequency": "m"
}
```

## Inflation Indicators

### Consumer Price Index (CPI)

Track headline inflation:

```javascript theme={null}
{
  "series_id": "CPIAUCSL",
  "observation_start": "2020-01-01",
  "units": "pc1"  // Percent change from year ago
}
```

### Core Inflation

CPI excluding volatile food and energy:

```javascript theme={null}
{
  "series_id": "CPILFESL",
  "observation_start": "2020-01-01",
  "units": "pc1"
}
```

<CodeGroup>
  ```javascript Headline CPI theme={null}
  {
    "series_id": "CPIAUCSL",
    "units": "pc1"
  }
  ```

  ```javascript Core CPI theme={null}
  {
    "series_id": "CPILFESL",
    "units": "pc1"
  }
  ```

  ```javascript PCE Price Index theme={null}
  {
    "series_id": "PCEPI",
    "units": "pc1"
  }
  ```

  ```javascript Core PCE theme={null}
  {
    "series_id": "PCEPILFE",
    "units": "pc1"
  }
  ```
</CodeGroup>

### Producer Price Index

Wholesale price changes:

```javascript theme={null}
{
  "series_id": "PPIACO",
  "observation_start": "2020-01-01",
  "units": "pc1"
}
```

## GDP and Growth

### Real GDP

Inflation-adjusted economic output:

```javascript theme={null}
{
  "series_id": "GDPC1",
  "observation_start": "2015-Q1",
  "units": "pca"  // Percent change at annual rate
}
```

### Nominal GDP

Current dollar GDP:

```javascript theme={null}
{
  "series_id": "GDP",
  "observation_start": "2015-Q1",
  "frequency": "q"
}
```

### GDP Components

<Tabs>
  <Tab title="Consumption">
    ```javascript theme={null}
    {
      "series_id": "PCEC",
      "observation_start": "2020-Q1"
    }
    ```
  </Tab>

  <Tab title="Investment">
    ```javascript theme={null}
    {
      "series_id": "GPDI",
      "observation_start": "2020-Q1"
    }
    ```
  </Tab>

  <Tab title="Government Spending">
    ```javascript theme={null}
    {
      "series_id": "GCE",
      "observation_start": "2020-Q1"
    }
    ```
  </Tab>

  <Tab title="Net Exports">
    ```javascript theme={null}
    {
      "series_id": "NETEXP",
      "observation_start": "2020-Q1"
    }
    ```
  </Tab>
</Tabs>

## Interest Rates

### Federal Funds Rate

The Fed's primary policy rate:

```javascript theme={null}
{
  "series_id": "DFF",
  "observation_start": "2020-01-01",
  "frequency": "d"
}
```

### Treasury Yields

<CardGroup>
  <Card title="2-Year Treasury" icon="clock">
    ```javascript theme={null}
    series_id: "DGS2"
    ```
  </Card>

  <Card title="10-Year Treasury" icon="clock">
    ```javascript theme={null}
    series_id: "DGS10"
    ```
  </Card>

  <Card title="30-Year Treasury" icon="clock">
    ```javascript theme={null}
    series_id: "DGS30"
    ```
  </Card>

  <Card title="Yield Curve Spread" icon="chart-area">
    ```javascript theme={null}
    series_id: "T10Y2Y"
    ```
  </Card>
</CardGroup>

### Mortgage Rates

30-year fixed mortgage rate:

```javascript theme={null}
{
  "series_id": "MORTGAGE30US",
  "observation_start": "2020-01-01",
  "frequency": "w"
}
```

## Financial Markets

### Stock Market Indices

```javascript theme={null}
// S&P 500
{
  "series_id": "SP500",
  "observation_start": "2023-01-01"
}

// Dow Jones Industrial Average
{
  "series_id": "DJIA",
  "observation_start": "2023-01-01"
}

// NASDAQ Composite
{
  "series_id": "NASDAQCOM",
  "observation_start": "2023-01-01"
}
```

### Exchange Rates

<AccordionGroup>
  <Accordion title="Major Currencies">
    ```javascript theme={null}
    // Euro
    { "series_id": "DEXUSEU" }

    // British Pound
    { "series_id": "DEXUSUK" }

    // Japanese Yen
    { "series_id": "DEXJPUS" }

    // Swiss Franc
    { "series_id": "DEXSZUS" }
    ```
  </Accordion>

  <Accordion title="Emerging Markets">
    ```javascript theme={null}
    // Chinese Yuan
    { "series_id": "DEXCHUS" }

    // Mexican Peso
    { "series_id": "DEXMXUS" }

    // Brazilian Real
    { "series_id": "DEXBZUS" }
    ```
  </Accordion>

  <Accordion title="Trade-Weighted">
    ```javascript theme={null}
    // Broad Dollar Index
    { "series_id": "DTWEXBGS" }

    // Advanced Economies
    { "series_id": "DTWEXAFEGS" }

    // Emerging Markets
    { "series_id": "DTWEXEMEGS" }
    ```
  </Accordion>
</AccordionGroup>

## Production Indicators

### Industrial Production

```javascript theme={null}
{
  "series_id": "INDPRO",
  "observation_start": "2020-01-01",
  "units": "pc1"
}
```

### Manufacturing

```javascript theme={null}
// Manufacturing Output
{
  "series_id": "IPMAN",
  "observation_start": "2020-01-01"
}

// Capacity Utilization
{
  "series_id": "TCU",
  "observation_start": "2020-01-01"
}
```

### Housing

<Steps>
  <Step title="Housing Starts">
    ```javascript theme={null}
    { "series_id": "HOUST" }
    ```
  </Step>

  <Step title="Building Permits">
    ```javascript theme={null}
    { "series_id": "PERMIT" }
    ```
  </Step>

  <Step title="Existing Home Sales">
    ```javascript theme={null}
    { "series_id": "EXHOSLUSM495S" }
    ```
  </Step>

  <Step title="Home Price Index">
    ```javascript theme={null}
    { "series_id": "CSUSHPISA" }
    ```
  </Step>
</Steps>

## Consumer Indicators

### Retail Sales

```javascript theme={null}
{
  "series_id": "RSXFS",
  "observation_start": "2020-01-01",
  "units": "pch"
}
```

### Consumer Confidence

```javascript theme={null}
// University of Michigan Consumer Sentiment
{
  "series_id": "UMCSENT",
  "observation_start": "2020-01-01"
}

// Conference Board Consumer Confidence
{
  "series_id": "CSCICP03USM665S",
  "observation_start": "2020-01-01"
}
```

### Personal Income and Spending

<Tabs>
  <Tab title="Personal Income">
    ```javascript theme={null}
    {
      "series_id": "PI",
      "observation_start": "2020-01-01",
      "units": "pc1"
    }
    ```
  </Tab>

  <Tab title="Personal Spending">
    ```javascript theme={null}
    {
      "series_id": "PCE",
      "observation_start": "2020-01-01",
      "units": "pc1"
    }
    ```
  </Tab>

  <Tab title="Savings Rate">
    ```javascript theme={null}
    {
      "series_id": "PSAVERT",
      "observation_start": "2020-01-01"
    }
    ```
  </Tab>
</Tabs>

## Money Supply

### Monetary Aggregates

```javascript theme={null}
// M1 Money Supply
{
  "series_id": "M1SL",
  "observation_start": "2020-01-01",
  "units": "pc1"
}

// M2 Money Supply
{
  "series_id": "M2SL",
  "observation_start": "2020-01-01",
  "units": "pc1"
}
```

## Searching for Indicators

Find indicators by topic:

```javascript theme={null}
// Search for inflation indicators
{
  "query": "inflation",
  "tags": ["monthly", "sa"],
  "limit": 20,
  "sort_by": "popularity"
}

// Search for employment
{
  "query": "employment",
  "tags": ["bls", "monthly"],
  "limit": 20
}
```

## Best Practices

<Warning>
  **Key considerations when working with indicators:**

  * **Frequency**: Match series frequencies for comparisons
  * **Seasonal Adjustment**: Use SA versions for trend analysis
  * **Units**: Verify units before calculations
  * **Revisions**: Economic data undergoes revisions
  * **Release Dates**: Check when data is typically updated
</Warning>

### Combining Multiple Indicators

```javascript theme={null}
// Create dashboard of key indicators
const dashboard = [
  { id: "UNRATE", name: "Unemployment" },
  { id: "CPIAUCSL", name: "CPI", transform: "pc1" },
  { id: "GDP", name: "GDP", transform: "pca" },
  { id: "DFF", name: "Fed Funds Rate" },
  { id: "SP500", name: "S&P 500" }
];

// Fetch all in date range
dashboard.forEach(indicator => {
  fred_get_series({
    series_id: indicator.id,
    observation_start: "2020-01-01",
    units: indicator.transform || "lin"
  });
});
```

## Next Steps

<CardGroup>
  <Card title="Time Series Analysis" icon="chart-line" href="/examples/time-series-analysis">
    Analyze trends and patterns
  </Card>

  <Card title="Data Transformations" icon="calculator" href="/examples/data-transformations">
    Transform data for analysis
  </Card>

  <Card title="Common Series" icon="bookmark" href="/resources/common-series">
    Popular indicator reference
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/overview">
    Tool documentation
  </Card>
</CardGroup>


# Time Series Analysis
Source: https://fred-mcp-server.amorelli.tech/examples/time-series-analysis

Analyzing trends, patterns, and relationships in economic data

# Time Series Analysis

Learn how to analyze economic trends, identify patterns, and compare time series data using the FRED MCP Server.

## Trend Analysis

### Long-Term Trends

Analyze unemployment over decades:

```javascript theme={null}
{
  "series_id": "UNRATE",
  "observation_start": "1980-01-01",
  "observation_end": "2024-10-01"
}
```

**Key insights to look for:**

* Cyclical peaks and troughs
* Long-term structural changes
* Recovery patterns after recessions

### Growth Rates

Calculate year-over-year growth:

```javascript theme={null}
{
  "series_id": "GDP",
  "observation_start": "2010-Q1",
  "units": "pc1"  // Percent change from year ago
}
```

<Tabs>
  <Tab title="Annualized Growth">
    ```javascript theme={null}
    {
      "series_id": "GDPC1",
      "units": "pca"  // Percent change at annual rate
    }
    ```
  </Tab>

  <Tab title="Quarter-over-Quarter">
    ```javascript theme={null}
    {
      "series_id": "GDPC1",
      "units": "pch"  // Percent change from prior period
    }
    ```
  </Tab>

  <Tab title="Year-over-Year">
    ```javascript theme={null}
    {
      "series_id": "GDPC1",
      "units": "pc1"  // Percent change from year ago
    }
    ```
  </Tab>
</Tabs>

## Cyclical Analysis

### Business Cycles

Identify recession periods using unemployment:

```javascript theme={null}
{
  "series_id": "UNRATE",
  "observation_start": "2000-01-01"
}
```

Combine with recession indicator:

```javascript theme={null}
{
  "series_id": "USREC",  // NBER Recession Indicator
  "observation_start": "2000-01-01"
}
```

<Note>
  **USREC** series: Value of 1 indicates recession period, 0 indicates expansion
</Note>

### Leading Indicators

Track predictive indicators:

```javascript theme={null}
// Leading Economic Index
{
  "series_id": "USSLIND",
  "observation_start": "2015-01-01"
}

// Building Permits (leads housing)
{
  "series_id": "PERMIT",
  "observation_start": "2015-01-01"
}

// Initial Claims (leads employment)
{
  "series_id": "ICSA",
  "observation_start": "2015-01-01"
}
```

## Seasonal Patterns

### Comparing SA vs NSA Data

```javascript theme={null}
// Seasonally Adjusted
{
  "series_id": "UNRATE",  // SA version
  "observation_start": "2023-01-01"
}

// Not Seasonally Adjusted
{
  "series_id": "UNRATENSA",  // NSA version
  "observation_start": "2023-01-01"
}
```

<CardGroup>
  <Card title="Seasonally Adjusted" icon="chart-line">
    Use for identifying underlying trends and business cycle turning points
  </Card>

  <Card title="Not Seasonally Adjusted" icon="calendar">
    Use for understanding actual seasonal hiring/firing patterns
  </Card>
</CardGroup>

### Seasonal Patterns

Retail sales show strong seasonality:

```javascript theme={null}
{
  "series_id": "RSXFSN",  // NSA retail sales
  "observation_start": "2020-01-01"
}
```

Expected patterns:

* **Q4 spike**: Holiday shopping season
* **Q1 dip**: Post-holiday slowdown
* **Summer**: Back-to-school season

## Correlation Analysis

### Related Series Comparison

Compare inflation measures:

```javascript theme={null}
// CPI
const cpi = {
  "series_id": "CPIAUCSL",
  "observation_start": "2020-01-01",
  "units": "pc1"
};

// PCE
const pce = {
  "series_id": "PCEPI",
  "observation_start": "2020-01-01",
  "units": "pc1"
};
```

### Leading-Lagging Relationships

<Steps>
  <Step title="Identify Leading Indicator">
    ```javascript theme={null}
    // Housing starts (leads GDP)
    { "series_id": "HOUST" }
    ```
  </Step>

  <Step title="Track Coincident Indicator">
    ```javascript theme={null}
    // Industrial production
    { "series_id": "INDPRO" }
    ```
  </Step>

  <Step title="Monitor Lagging Indicator">
    ```javascript theme={null}
    // Unemployment (lags recession end)
    { "series_id": "UNRATE" }
    ```
  </Step>
</Steps>

### Interest Rate Relationships

Yield curve analysis:

```javascript theme={null}
// 10-Year Treasury
const ten_year = {
  "series_id": "DGS10",
  "observation_start": "2020-01-01"
};

// 2-Year Treasury
const two_year = {
  "series_id": "DGS2",
  "observation_start": "2020-01-01"
};

// Pre-calculated spread
const spread = {
  "series_id": "T10Y2Y",  // 10Y - 2Y spread
  "observation_start": "2020-01-01"
};
```

<Warning>
  **Inverted Yield Curve** (negative spread) has historically preceded recessions
</Warning>

## Volatility Analysis

### Price Volatility

Measure inflation volatility:

```javascript theme={null}
{
  "series_id": "CPIAUCSL",
  "observation_start": "2015-01-01",
  "units": "pch"  // Month-to-month changes
}
```

High volatility periods often indicate:

* Economic uncertainty
* Supply shocks
* Policy transitions

### Financial Market Volatility

VIX Index (market volatility):

```javascript theme={null}
{
  "series_id": "VIXCLS",
  "observation_start": "2020-01-01"
}
```

## Structural Breaks

### Identifying Regime Changes

Look for significant structural changes:

```javascript theme={null}
// Labor force participation
{
  "series_id": "CIVPART",
  "observation_start": "1980-01-01"
}
```

Notable breaks:

* **2000**: Women's participation peak
* **2008**: Financial crisis impact
* **2020**: Pandemic shock

### Policy Changes

Federal Funds Rate regime shifts:

```javascript theme={null}
{
  "series_id": "DFF",
  "observation_start": "2000-01-01"
}
```

Regimes:

* **Pre-2008**: Normal monetary policy
* **2008-2015**: Zero lower bound
* **2015-2019**: Gradual normalization
* **2020-2022**: Emergency response
* **2022-present**: Aggressive tightening

## Smoothing and Filtering

### Moving Averages

Smooth noisy data using longer periods:

```javascript theme={null}
// Weekly initial claims (volatile)
{
  "series_id": "ICSA",
  "observation_start": "2020-01-01"
}

// 4-week moving average (smoother)
{
  "series_id": "IC4WSA",
  "observation_start": "2020-01-01"
}
```

### Continuous Claims vs Initial Claims

<Tabs>
  <Tab title="Initial Claims">
    ```javascript theme={null}
    // New unemployment insurance claims
    { "series_id": "ICSA" }
    ```

    More volatile, faster signal
  </Tab>

  <Tab title="Continuing Claims">
    ```javascript theme={null}
    // Ongoing unemployment insurance
    { "series_id": "CCSA" }
    ```

    Smoother, persistent signal
  </Tab>
</Tabs>

## Growth Decomposition

### GDP Components

Analyze which components drive growth:

```javascript theme={null}
// Total GDP
const gdp = { "series_id": "GDP" };

// Consumption (typically ~68%)
const consumption = { "series_id": "PCEC" };

// Investment (typically ~17%)
const investment = { "series_id": "GPDI" };

// Government (typically ~17%)
const government = { "series_id": "GCE" };

// Net Exports (often negative)
const net_exports = { "series_id": "NETEXP" };
```

### Inflation Decomposition

Core vs headline inflation:

```javascript theme={null}
// Headline CPI
{
  "series_id": "CPIAUCSL",
  "units": "pc1"
}

// Core CPI (ex food & energy)
{
  "series_id": "CPILFESL",
  "units": "pc1"
}

// Food CPI
{
  "series_id": "CPIUFDSL",
  "units": "pc1"
}

// Energy CPI
{
  "series_id": "CPIENGSL",
  "units": "pc1"
}
```

## Real vs Nominal

### Inflation Adjustment

Compare nominal and real values:

```javascript theme={null}
// Nominal Wages
{
  "series_id": "CES0500000003",  // Avg hourly earnings
  "observation_start": "2010-01-01"
}

// Real Wages (inflation-adjusted)
{
  "series_id": "CES0500000030",  // Real avg hourly earnings
  "observation_start": "2010-01-01"
}
```

<Tip>
  Real values show actual purchasing power changes, while nominal values include inflation
</Tip>

## Advanced Patterns

### Phillips Curve

Inflation vs unemployment relationship:

```javascript theme={null}
// Unemployment Rate
const unemployment = {
  "series_id": "UNRATE",
  "observation_start": "2000-01-01"
};

// Core CPI Inflation
const inflation = {
  "series_id": "CPILFESL",
  "observation_start": "2000-01-01",
  "units": "pc1"
};
```

**Expected relationship:** Higher unemployment → Lower inflation

### Okun's Law

GDP growth vs unemployment changes:

```javascript theme={null}
// Real GDP Growth
const gdp_growth = {
  "series_id": "GDPC1",
  "units": "pca"
};

// Unemployment Rate
const unemployment = {
  "series_id": "UNRATE"
};
```

**Expected relationship:** 1% GDP growth above trend → \~0.5% unemployment decline

## Forecasting Indicators

### Nowcasting

Current quarter GDP estimates:

```javascript theme={null}
// GDPNow (Atlanta Fed nowcast)
{
  "series_id": "GDPNOW",
  "observation_start": "2024-Q3"
}
```

### Survey-Based Forecasts

```javascript theme={null}
// Philadelphia Fed Manufacturing Index
{
  "series_id": "USPHCI",
  "observation_start": "2020-01-01"
}

// Consumer Expectations
{
  "series_id": "UMCSENT1Y",
  "observation_start": "2020-01-01"
}
```

## Practical Analysis Workflows

### Recession Analysis

<Steps>
  <Step title="Identify Recession Periods">
    Use USREC to mark recessions
  </Step>

  <Step title="Track Key Indicators">
    * Unemployment (rises during recession)
    * GDP (declines during recession)
    * Retail sales (weakens)
  </Step>

  <Step title="Analyze Recovery">
    * Duration from peak to trough
    * Time to pre-recession levels
    * Shape of recovery (V, U, W, L)
  </Step>

  <Step title="Compare Across Recessions">
    * 2001 (Tech bubble)
    * 2008 (Financial crisis)
    * 2020 (Pandemic)
  </Step>
</Steps>

### Policy Impact Analysis

Federal Reserve rate changes:

```javascript theme={null}
// Fed Funds Rate
{
  "series_id": "DFF",
  "observation_start": "2015-01-01"
}

// Mortgage Rates (responds to policy)
{
  "series_id": "MORTGAGE30US",
  "observation_start": "2015-01-01"
}

// Housing Starts (affected by mortgage rates)
{
  "series_id": "HOUST",
  "observation_start": "2015-01-01"
}
```

## Visualization Best Practices

<AccordionGroup>
  <Accordion title="Time Period Selection">
    * **Short-term**: 1-2 years for recent trends
    * **Medium-term**: 5-10 years for cyclical patterns
    * **Long-term**: 20+ years for structural changes
  </Accordion>

  <Accordion title="Frequency Matching">
    Align frequencies when comparing:

    * Daily: Interest rates, stock prices
    * Monthly: Most economic indicators
    * Quarterly: GDP and national accounts
  </Accordion>

  <Accordion title="Scale Considerations">
    * Use same units for direct comparison
    * Index to common base for relative comparison
    * Use dual axes carefully (can be misleading)
  </Accordion>

  <Accordion title="Transformation Choice">
    * **Levels**: Show absolute values
    * **Growth rates**: Show momentum
    * **Indexed**: Show relative performance
    * **Normalized**: Show deviations from average
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Data Transformations" icon="calculator" href="/examples/data-transformations">
    Learn transformation techniques
  </Card>

  <Card title="Advanced Queries" icon="magnifying-glass-chart" href="/examples/advanced-queries">
    Complex search patterns
  </Card>

  <Card title="Economic Analysis" icon="chart-mixed" href="/use-cases/economic-analysis">
    Comprehensive analysis workflows
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/fred-get-series">
    Series retrieval documentation
  </Card>
</CardGroup>


# Installation
Source: https://fred-mcp-server.amorelli.tech/installation

Comprehensive installation guide for all platforms and methods

# Installation Guide

This guide covers all installation methods for the FRED MCP Server across different platforms and deployment scenarios.

## Prerequisites

<CardGroup>
  <Card title="FRED API Key" icon="key">
    Required for accessing FRED data. Get your free key at [fred.stlouisfed.org](https://fred.stlouisfed.org/docs/api/api_key.html)
  </Card>

  <Card title="Node.js 18+" icon="node">
    Required for running the server. Download from [nodejs.org](https://nodejs.org)
  </Card>
</CardGroup>

## Installation Methods

### Method 1: Automatic Installation (Recommended)

<Tabs>
  <Tab title="NPM Global">
    Install globally for system-wide access:

    ```bash theme={null}
    # Install globally
    npm install -g fred-mcp-server

    # Verify installation
    fred-mcp-server --version
    ```

    **Benefits:**

    * Available system-wide
    * Easy updates via npm
    * Simple command-line usage
  </Tab>

  <Tab title="NPM Local">
    Install in a specific project:

    ```bash theme={null}
    # Create project directory
    mkdir my-fred-project
    cd my-fred-project

    # Initialize and install
    npm init -y
    npm install fred-mcp-server

    # Run with npx
    npx fred-mcp-server
    ```

    **Benefits:**

    * Project-specific installation
    * Version control friendly
    * No global dependencies
  </Tab>
</Tabs>

### Method 2: From Source

<Steps>
  <Step title="Clone Repository">
    ```bash theme={null}
    git clone https://github.com/stefanoamorelli/fred-mcp-server.git
    cd fred-mcp-server
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    # Using pnpm (recommended)
    pnpm install

    # Or using npm
    npm install

    # Or using yarn
    yarn install
    ```
  </Step>

  <Step title="Build the Project">
    ```bash theme={null}
    # Build TypeScript
    pnpm build

    # Or with npm
    npm run build
    ```
  </Step>

  <Step title="Verify Build">
    ```bash theme={null}
    # Test the build
    node build/index.js --version
    ```
  </Step>
</Steps>

### Method 3: Docker

<Tabs>
  <Tab title="Pre-built Image">
    Use the official Docker image:

    ```bash theme={null}
    # Pull the latest image
    docker pull stefanoamorelli/fred-mcp-server:latest

    # Run the container
    docker run -i --rm \
      -e FRED_API_KEY=your_api_key_here \
      stefanoamorelli/fred-mcp-server:latest
    ```
  </Tab>

  <Tab title="Build Custom Image">
    Build your own Docker image:

    ```dockerfile theme={null}
    # Dockerfile
    FROM node:18-alpine

    WORKDIR /app

    # Copy package files
    COPY package*.json ./
    RUN npm ci --only=production

    # Copy application
    COPY . .
    RUN npm run build

    # Set entrypoint
    ENTRYPOINT ["node", "build/index.js"]
    ```

    Build and run:

    ```bash theme={null}
    docker build -t my-fred-mcp .
    docker run -i --rm -e FRED_API_KEY=key my-fred-mcp
    ```
  </Tab>
</Tabs>

## Client Configuration

### Claude Desktop

<Accordion title="Configuration file locations">
  * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  * **Linux**: `~/.config/claude/claude_desktop_config.json`
</Accordion>

<Tabs>
  <Tab title="Standard Setup">
    ```json theme={null}
    {
      "mcpServers": {
        "fred-mcp": {
          "command": "fred-mcp-server",
          "env": {
            "FRED_API_KEY": "your_api_key_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Local Build">
    ```json theme={null}
    {
      "mcpServers": {
        "fred-mcp": {
          "command": "node",
          "args": ["/path/to/fred-mcp-server/build/index.js"],
          "env": {
            "FRED_API_KEY": "your_api_key_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Docker">
    ```json theme={null}
    {
      "mcpServers": {
        "fred-mcp": {
          "command": "docker",
          "args": [
            "run",
            "-i",
            "--rm",
            "-e",
            "FRED_API_KEY=your_api_key_here",
            "stefanoamorelli/fred-mcp-server:latest"
          ]
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Other MCP Clients

<AccordionGroup>
  <Accordion title="VSCode Extension">
    Configure in `.vscode/settings.json`:

    ```json theme={null}
    {
      "mcp.servers": {
        "fred": {
          "command": "fred-mcp-server",
          "env": {
            "FRED_API_KEY": "${env:FRED_API_KEY}"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Command Line Client">
    Use with any MCP CLI client:

    ```bash theme={null}
    # Set environment variable
    export FRED_API_KEY="your_api_key"

    # Run with MCP CLI
    mcp-cli connect fred-mcp-server
    ```
  </Accordion>

  <Accordion title="Python Client">
    Use with Python MCP client:

    ```python theme={null}
    from mcp import Client
    import os

    # Configure client
    client = Client()
    client.connect(
        command="fred-mcp-server",
        env={"FRED_API_KEY": os.getenv("FRED_API_KEY")}
    )

    # Use the client
    result = client.call_tool(
        "fred_get_series",
        {"series_id": "GDP", "limit": 10}
    )
    ```
  </Accordion>
</AccordionGroup>

## Environment Variables

<ParamField type="string">
  Your FRED API key from fred.stlouisfed.org
</ParamField>

<ParamField type="string">
  Optional: Override the FRED API base URL
</ParamField>

<ParamField type="string">
  Optional: Set logging level (debug, info, warn, error)
</ParamField>

## Platform-Specific Instructions

### macOS

<Steps>
  <Step title="Install Prerequisites">
    ```bash theme={null}
    # Install Homebrew if needed
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    # Install Node.js
    brew install node
    ```
  </Step>

  <Step title="Install FRED MCP">
    ```bash theme={null}
    npm install -g fred-mcp-server
    ```
  </Step>

  <Step title="Configure Claude">
    ```bash theme={null}
    # Open config in editor
    code ~/Library/Application\ Support/Claude/claude_desktop_config.json
    ```
  </Step>
</Steps>

### Windows

<Steps>
  <Step title="Install Prerequisites">
    1. Download Node.js from [nodejs.org](https://nodejs.org)
    2. Run the installer with default settings
    3. Open PowerShell or Command Prompt as Administrator
  </Step>

  <Step title="Install FRED MCP">
    ```powershell theme={null}
    npm install -g fred-mcp-server
    ```
  </Step>

  <Step title="Configure Claude">
    ```powershell theme={null}
    # Open config directory
    explorer %APPDATA%\Claude

    # Edit claude_desktop_config.json
    ```
  </Step>
</Steps>

### Linux

<Steps>
  <Step title="Install Prerequisites">
    ```bash theme={null}
    # Ubuntu/Debian
    sudo apt update
    sudo apt install nodejs npm

    # Fedora
    sudo dnf install nodejs npm

    # Arch
    sudo pacman -S nodejs npm
    ```
  </Step>

  <Step title="Install FRED MCP">
    ```bash theme={null}
    sudo npm install -g fred-mcp-server
    ```
  </Step>

  <Step title="Configure Claude">
    ```bash theme={null}
    # Create config directory if needed
    mkdir -p ~/.config/claude

    # Edit configuration
    nano ~/.config/claude/claude_desktop_config.json
    ```
  </Step>
</Steps>

## Verification

### Test Installation

<CodeGroup>
  ```bash Command Line theme={null}
  # Test the server directly
  FRED_API_KEY=your_key fred-mcp-server

  # Should output MCP initialization message
  ```

  ```bash Docker Test theme={null}
  # Test Docker installation
  docker run -i --rm \
    -e FRED_API_KEY=your_key \
    stefanoamorelli/fred-mcp-server:latest \
    <<< '{"jsonrpc":"2.0","method":"tools/list","id":1}'
  ```

  ```javascript Node.js Test theme={null}
  // test.js
  const { spawn } = require('child_process');

  const server = spawn('fred-mcp-server', [], {
    env: { ...process.env, FRED_API_KEY: 'your_key' }
  });

  server.stdout.on('data', (data) => {
    console.log(`Server: ${data}`);
  });
  ```
</CodeGroup>

### Troubleshooting

<AccordionGroup>
  <Accordion title="Command not found">
    **Issue**: `fred-mcp-server: command not found`

    **Solutions**:

    1. Ensure Node.js is installed: `node --version`
    2. Check npm global bin path: `npm bin -g`
    3. Add npm bin to PATH: `export PATH=$PATH:$(npm bin -g)`
    4. Reinstall: `npm install -g fred-mcp-server`
  </Accordion>

  <Accordion title="Permission denied">
    **Issue**: Permission errors during installation

    **Solutions**:

    * macOS/Linux: Use `sudo npm install -g fred-mcp-server`
    * Windows: Run as Administrator
    * Alternative: Install locally without `-g` flag
  </Accordion>

  <Accordion title="API Key errors">
    **Issue**: "Invalid API key" or authentication errors

    **Solutions**:

    1. Verify key at [fred.stlouisfed.org](https://fred.stlouisfed.org)
    2. Check for typos in configuration
    3. Ensure proper JSON formatting
    4. Test key with curl:

    ```bash theme={null}
    curl "https://api.stlouisfed.org/fred/series?series_id=GDP&api_key=YOUR_KEY&file_type=json"
    ```
  </Accordion>

  <Accordion title="Docker issues">
    **Issue**: Docker container exits immediately

    **Solutions**:

    1. Run with `-it` flags for interactive mode
    2. Check Docker logs: `docker logs container_id`
    3. Verify environment variables are passed correctly
    4. Ensure Docker daemon is running
  </Accordion>
</AccordionGroup>

## Updating

### Update Methods

<Tabs>
  <Tab title="NPM Update">
    ```bash theme={null}
    # Update globally installed version
    npm update -g fred-mcp-server

    # Or reinstall latest
    npm install -g fred-mcp-server@latest
    ```
  </Tab>

  <Tab title="Git Update">
    ```bash theme={null}
    # In your cloned repository
    git pull origin main
    pnpm install
    pnpm build
    ```
  </Tab>

  <Tab title="Docker Update">
    ```bash theme={null}
    # Pull latest image
    docker pull stefanoamorelli/fred-mcp-server:latest

    # Remove old image (optional)
    docker image prune
    ```
  </Tab>
</Tabs>

## Next Steps

<CardGroup>
  <Card title="Configuration" icon="gear" href="/configuration">
    Advanced configuration options
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Explore available tools
  </Card>

  <Card title="Examples" icon="flask" href="/examples/basic-usage">
    Start using FRED data
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/resources/troubleshooting">
    Common issues and solutions
  </Card>
</CardGroup>


# Introduction
Source: https://fred-mcp-server.amorelli.tech/introduction

Welcome to the Federal Reserve Economic Data MCP Server documentation

<img alt="FRED MCP Server Hero Light" />

<img alt="FRED MCP Server Hero Dark" />

# Federal Reserve Economic Data MCP Server

<Note>
  **About**: This open-source project was created by Stefano Amorelli and is not affiliated with, sponsored by, or endorsed by the Federal Reserve or the Federal Reserve Bank of St. Louis. "FRED" is a registered trademark of the Federal Reserve Bank of St. Louis, used here for descriptive purposes only.
</Note>

<Warning>
  **Important**: By using this software, you agree to comply with the [FRED® API Terms of Use](https://fred.stlouisfed.org/docs/api/terms_of_use.html). Users are solely responsible for ensuring their use of FRED data complies with all applicable terms and conditions. The developers of this software are not responsible for any misuse or violations of FRED's terms of service.
</Warning>

A powerful Model Context Protocol (MCP) server that provides universal access to all **800,000+ Federal Reserve Economic Data (FRED®)** time series through three comprehensive tools. Built for AI assistants, researchers, and developers who need reliable economic data.

## What is FRED MCP Server?

The FRED MCP Server bridges the gap between AI assistants and the vast repository of economic data maintained by the Federal Reserve Bank of St. Louis. It enables:

<CardGroup>
  <Card title="Comprehensive Data Access" icon="database" href="/core-concepts/fred-data">
    Access over 800,000 economic time series from 100+ sources
  </Card>

  <Card title="AI-Native Integration" icon="robot" href="/core-concepts/mcp-protocol">
    Seamlessly integrate with Claude, ChatGPT, and other AI assistants
  </Card>

  <Card title="Advanced Analytics" icon="chart-line" href="/api-reference/fred-get-series">
    Built-in data transformations and frequency adjustments
  </Card>

  <Card title="Real-Time Updates" icon="clock" href="/examples/economic-indicators">
    Get the latest economic indicators as they're released
  </Card>
</CardGroup>

## Why Use FRED MCP Server?

### For Researchers and Analysts

* **Instant Access**: Query any economic indicator without manual downloads
* **Historical Data**: Access decades of historical economic data
* **Automated Workflows**: Build reproducible research pipelines
* **Data Transformations**: Apply percentage changes, growth rates, and more

### For AI Application Developers

* **MCP Standard**: Built on the open Model Context Protocol standard
* **Type-Safe**: Full TypeScript support with comprehensive type definitions
* **Error Handling**: Robust error handling and validation
* **Rate Limiting**: Built-in rate limiting to respect API constraints

### For Financial Professionals

* **Market Indicators**: Track GDP, unemployment, inflation, and more
* **Policy Analysis**: Monitor Federal Reserve policy indicators
* **International Data**: Access global economic indicators
* **Custom Aggregations**: Transform data to match your analysis needs

## Key Features

<AccordionGroup>
  <Accordion title="Browse Economic Categories" icon="folder-tree">
    Navigate through FRED's hierarchical category structure to discover available data series. Browse by topic, source, or release schedule.
  </Accordion>

  <Accordion title="Search Capabilities" icon="magnifying-glass">
    Search across all 800,000+ series using keywords, tags, or specific filters. Find exactly the data you need quickly.
  </Accordion>

  <Accordion title="Data Retrieval & Transformation" icon="arrow-right-arrow-left">
    Retrieve any series with built-in transformations including growth rates, percentage changes, logarithmic scaling, and frequency conversions.
  </Accordion>

  <Accordion title="Real-Time Updates" icon="arrows-rotate">
    Access the latest economic data as soon as it's released by the Federal Reserve and other authoritative sources.
  </Accordion>
</AccordionGroup>

## Quick Example

Here's how easy it is to get started with FRED MCP Server:

<CodeGroup>
  ```typescript Claude Desktop theme={null}
  // Ask Claude:
  "What's the current US unemployment rate?"

  // Claude uses fred_get_series tool:
  {
    "tool": "fred_get_series",
    "params": {
      "series_id": "UNRATE",
      "limit": 12
    }
  }
  ```

  ```python Research Script theme={null}
  # Use with any MCP client
  client.call_tool(
      "fred_search",
      {
          "search_text": "inflation",
          "tag_names": "usa,monthly",
          "limit": 5
      }
  )
  ```

  ```javascript Analysis theme={null}
  // Get GDP growth rate
  const gdpGrowth = await mcp.callTool(
    "fred_get_series",
    {
      series_id: "GDP",
      units: "pc1", // Percent change from year ago
      frequency: "q"  // Quarterly
    }
  );
  ```
</CodeGroup>

## Academic Citation

If you use this project in your research, please cite it:

<Tabs>
  <Tab title="APA">
    ```text theme={null}
    Amorelli, S. (2025). Federal Reserve Economic Data MCP (Model Context
    Protocol) Server (Version 1.0.2) [Computer software]. Zenodo.
    https://doi.org/10.5281/zenodo.14536707
    ```
  </Tab>

  <Tab title="BibTeX">
    ```bibtex theme={null}
    @software{amorelli_2025_14536707,
      author       = {Amorelli, Stefano},
      title        = {{Federal Reserve Economic Data MCP (Model Context
                       Protocol) Server}},
      month        = jan,
      year         = 2025,
      publisher    = {Zenodo},
      version      = {1.0.2},
      doi          = {10.5281/zenodo.14536707},
      url          = {https://doi.org/10.5281/zenodo.14536707}
    }
    ```
  </Tab>
</Tabs>

## Next Steps

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Get up and running in under 5 minutes
  </Card>

  <Card title="Installation Guide" icon="download" href="/installation">
    Detailed installation instructions for all platforms
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Complete reference for all available tools
  </Card>

  <Card title="Examples" icon="flask" href="/examples/basic-usage">
    Learn by example with real-world use cases
  </Card>
</CardGroup>

## Community & Support

* **GitHub**: [stefanoamorelli/fred-mcp-server](https://github.com/stefanoamorelli/fred-mcp-server)
* **NPM Package**: [fred-mcp-server](https://www.npmjs.com/package/fred-mcp-server)
* **Author**: [Stefano Amorelli](https://amorelli.tech)
* **License**: AGPL-3.0

<Info>
  Join our community on [GitHub Discussions](https://github.com/stefanoamorelli/fred-mcp-server/discussions) to share ideas, ask questions, and connect with other users.
</Info>


# Quick Start
Source: https://fred-mcp-server.amorelli.tech/quickstart

Get up and running with FRED MCP Server in 5 minutes

# Quick Start Guide

Get the FRED MCP Server running with your AI assistant in just a few minutes. This guide will walk you through the fastest path to start querying economic data.

## Prerequisites

<Steps>
  <Step title="Get a FRED API Key">
    Visit [fred.stlouisfed.org/docs/api/api\_key.html](https://fred.stlouisfed.org/docs/api/api_key.html) to register for a free API key.

    <Info>
      The API key is free and provides access to all FRED data. Registration takes less than a minute.
    </Info>
  </Step>

  <Step title="Install Claude Desktop (or another MCP client)">
    Download [Claude Desktop](https://claude.ai/download) or ensure you have another MCP-compatible client installed.
  </Step>
</Steps>

## Installation

Choose your preferred installation method:

<Tabs>
  <Tab title="NPM Global">
    Install globally via NPM:

    ```bash theme={null}
    npm install -g fred-mcp-server
    ```

    Then add to your Claude Desktop config:

    ```json theme={null}
    {
      "mcpServers": {
        "fred-mcp": {
          "command": "fred-mcp-server",
          "env": {
            "FRED_API_KEY": "your_api_key_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Docker">
    Use the pre-built Docker image:

    ```json theme={null}
    {
      "mcpServers": {
        "fred-mcp": {
          "command": "docker",
          "args": [
            "run",
            "-i",
            "--rm",
            "-e",
            "FRED_API_KEY=your_api_key_here",
            "stefanoamorelli/fred-mcp-server:latest"
          ]
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Configuration

### Claude Desktop Configuration

<Accordion title="Finding your configuration file">
  The Claude Desktop configuration file location varies by platform:

  * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  * **Linux**: `~/.config/claude/claude_desktop_config.json`
</Accordion>

Edit your `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "fred-mcp": {
      "command": "fred-mcp-server",
      "env": {
        "FRED_API_KEY": "your_actual_api_key_here"
      }
    }
  }
}
```

<Warning>
  Replace `your_actual_api_key_here` with your actual FRED API key. Keep this key secure and never commit it to version control.
</Warning>

## Verify Installation

After configuration, restart Claude Desktop and verify the server is working:

<Steps>
  <Step title="Restart Claude Desktop">
    Completely quit and restart Claude Desktop to load the new configuration.
  </Step>

  <Step title="Check MCP Connection">
    In Claude, you should see "fred-mcp" in the MCP servers list (look for the 🔌 icon).
  </Step>

  <Step title="Test a Query">
    Try asking Claude:

    ```text theme={null}
    "What's the current US GDP growth rate?"
    ```

    Claude should use the `fred_get_series` tool to fetch the data.
  </Step>
</Steps>

## Your First Queries

Now that you're set up, try these example queries to explore FRED data:

### Basic Economic Indicators

<CodeGroup>
  ```text Unemployment Rate theme={null}
  "Show me the US unemployment rate for the last year"
  ```

  ```text Inflation theme={null}
  "What's the current inflation rate (CPI)?"
  ```

  ```text GDP Growth theme={null}
  "Get quarterly GDP growth rates for 2024"
  ```
</CodeGroup>

### Advanced Queries

<CodeGroup>
  ```text Search for Data theme={null}
  "Search for all inflation-related indicators"
  ```

  ```text Browse Categories theme={null}
  "Browse available economic categories"
  ```

  ```text Historical Analysis theme={null}
  "Compare unemployment rates during the last three recessions"
  ```
</CodeGroup>

## Common Series IDs

Here are some frequently used FRED series IDs:

<AccordionGroup>
  <Accordion title="Key Economic Indicators">
    * **GDP**: Real Gross Domestic Product
    * **UNRATE**: Unemployment Rate
    * **CPIAUCSL**: Consumer Price Index (All Urban Consumers)
    * **CPILFESL**: Core CPI (Less Food and Energy)
    * **PAYEMS**: All Employees, Total Nonfarm Payrolls
  </Accordion>

  <Accordion title="Interest Rates">
    * **DFF**: Federal Funds Effective Rate
    * **DGS10**: 10-Year Treasury Rate
    * **DGS2**: 2-Year Treasury Rate
    * **TB3MS**: 3-Month Treasury Bill
    * **MORTGAGE30US**: 30-Year Fixed Rate Mortgage Average
  </Accordion>

  <Accordion title="Stock Market">
    * **SP500**: S\&P 500 Index
    * **DJIA**: Dow Jones Industrial Average
    * **NASDAQCOM**: NASDAQ Composite Index
    * **VIXCLS**: CBOE Volatility Index (VIX)
  </Accordion>

  <Accordion title="Housing">
    * **HOUST**: Housing Starts
    * **CSUSHPISA**: Case-Shiller Home Price Index
    * **PERMIT**: Building Permits
    * **MSACSR**: Monthly Supply of Houses
  </Accordion>
</AccordionGroup>

## Example Conversations

### Economic Analysis

```text theme={null}
You: "Analyze the relationship between unemployment and inflation over the last decade"

Claude: I'll analyze the relationship between unemployment and inflation using FRED data...
[Uses fred_get_series to fetch UNRATE and CPIAUCSL data]
[Provides analysis with data visualization]
```

### Market Monitoring

```text theme={null}
You: "Create a dashboard of key economic indicators for Q4 2024"

Claude: I'll gather the key economic indicators for Q4 2024...
[Uses multiple fred_get_series calls to fetch GDP, UNRATE, CPI, etc.]
[Presents organized data summary]
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Server not appearing in Claude">
    1. Ensure configuration file is valid JSON
    2. Check the file path is correct for your OS
    3. Restart Claude Desktop completely
    4. Verify the server command is in your PATH
  </Accordion>

  <Accordion title="API Key errors">
    * Verify your API key is valid at [fred.stlouisfed.org](https://fred.stlouisfed.org)
    * Ensure the key is properly quoted in the config
    * Check for extra spaces or characters
  </Accordion>

  <Accordion title="No data returned">
    * Check the series ID is correct (case-sensitive)
    * Verify the date range includes available data
    * Try a known working series like "GDP" or "UNRATE"
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Installation Guide" icon="download" href="/installation">
    Detailed installation for all platforms
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Complete documentation of all tools
  </Card>

  <Card title="Examples" icon="flask" href="/examples/basic-usage">
    Learn with practical examples
  </Card>

  <Card title="Common Series" icon="list" href="/resources/common-series">
    Popular FRED series reference
  </Card>
</CardGroup>


# Common Series Reference
Source: https://fred-mcp-server.amorelli.tech/resources/common-series

Quick reference for frequently used FRED series

# Common FRED Series Reference

Quick reference guide for the most frequently used FRED economic data series.

## Major Economic Indicators

### GDP & Growth

| Series ID          | Description            | Frequency | Units                       |
| ------------------ | ---------------------- | --------- | --------------------------- |
| **GDP**            | Gross Domestic Product | Quarterly | Billions of Dollars         |
| **GDPC1**          | Real GDP               | Quarterly | Billions of Chained Dollars |
| **GDPPOT**         | Real Potential GDP     | Quarterly | Billions of Chained Dollars |
| **NYGDPMKTPCDWLD** | World GDP Per Capita   | Annual    | Constant 2015 US\$          |
| **GDPDEF**         | GDP Deflator           | Quarterly | Index 2017=100              |

### Employment & Labor

| Series ID         | Description                               | Frequency | Units     |
| ----------------- | ----------------------------------------- | --------- | --------- |
| **UNRATE**        | Unemployment Rate                         | Monthly   | Percent   |
| **U6RATE**        | Total Unemployed Plus Marginally Attached | Monthly   | Percent   |
| **PAYEMS**        | All Employees, Total Nonfarm              | Monthly   | Thousands |
| **CIVPART**       | Labor Force Participation Rate            | Monthly   | Percent   |
| **EMRATIO**       | Employment-Population Ratio               | Monthly   | Percent   |
| **CES0500000003** | Average Hourly Earnings                   | Monthly   | Dollars   |
| **ICSA**          | Initial Jobless Claims                    | Weekly    | Number    |

### Inflation Indicators

| Series ID    | Description                        | Frequency | Units             |
| ------------ | ---------------------------------- | --------- | ----------------- |
| **CPIAUCSL** | Consumer Price Index for All Urban | Monthly   | Index 1982-84=100 |
| **CPILFESL** | Core CPI (Less Food & Energy)      | Monthly   | Index 1982-84=100 |
| **PCEPI**    | PCE Price Index                    | Monthly   | Index 2017=100    |
| **PCEPILFE** | Core PCE Price Index               | Monthly   | Index 2017=100    |
| **DFEDTARU** | Federal Reserve Target Rate Upper  | Daily     | Percent           |
| **PPIFIS**   | Producer Price Index               | Monthly   | Index 1982=100    |

## Interest Rates

### Federal Reserve Rates

| Series ID    | Description                  | Frequency | Units   |
| ------------ | ---------------------------- | --------- | ------- |
| **DFF**      | Federal Funds Effective Rate | Daily     | Percent |
| **DFEDTARU** | Fed Target Upper Bound       | Daily     | Percent |
| **DFEDTARL** | Fed Target Lower Bound       | Daily     | Percent |
| **FEDFUNDS** | Federal Funds Rate (Monthly) | Monthly   | Percent |
| **IOER**     | Interest on Excess Reserves  | Daily     | Percent |

### Treasury Yields

| Series ID  | Description      | Frequency | Units   |
| ---------- | ---------------- | --------- | ------- |
| **DGS1MO** | 1-Month Treasury | Daily     | Percent |
| **DGS3MO** | 3-Month Treasury | Daily     | Percent |
| **DGS6MO** | 6-Month Treasury | Daily     | Percent |
| **DGS1**   | 1-Year Treasury  | Daily     | Percent |
| **DGS2**   | 2-Year Treasury  | Daily     | Percent |
| **DGS5**   | 5-Year Treasury  | Daily     | Percent |
| **DGS10**  | 10-Year Treasury | Daily     | Percent |
| **DGS30**  | 30-Year Treasury | Daily     | Percent |

### Yield Spreads

| Series ID        | Description           | Frequency | Units   |
| ---------------- | --------------------- | --------- | ------- |
| **T10Y2Y**       | 10-Year minus 2-Year  | Daily     | Percent |
| **T10Y3M**       | 10-Year minus 3-Month | Daily     | Percent |
| **TEDRATE**      | TED Spread            | Daily     | Percent |
| **BAMLH0A0HYM2** | High Yield Spread     | Daily     | Percent |

### Consumer Rates

| Series ID         | Description               | Frequency | Units   |
| ----------------- | ------------------------- | --------- | ------- |
| **MORTGAGE30US**  | 30-Year Fixed Mortgage    | Weekly    | Percent |
| **MORTGAGE15US**  | 15-Year Fixed Mortgage    | Weekly    | Percent |
| **DPRIME**        | Bank Prime Loan Rate      | Daily     | Percent |
| **TERMCBCCALLNS** | Credit Card Interest Rate | Monthly   | Percent |

## Stock Market

### Major Indices

| Series ID         | Description                  | Frequency | Units |
| ----------------- | ---------------------------- | --------- | ----- |
| **SP500**         | S\&P 500                     | Daily     | Index |
| **DJIA**          | Dow Jones Industrial Average | Daily     | Index |
| **NASDAQCOM**     | NASDAQ Composite             | Daily     | Index |
| **WILL5000INDFC** | Wilshire 5000                | Daily     | Index |
| **VIXCLS**        | CBOE Volatility Index        | Daily     | Index |

### Market Indicators

| Series ID            | Description                | Frequency | Units    |
| -------------------- | -------------------------- | --------- | -------- |
| **DDDM01USA156NWDB** | Stock Market Cap to GDP    | Annual    | Percent  |
| **SHILLER PE RATIO** | Shiller PE Ratio           | Monthly   | Ratio    |
| **DSPIC96**          | Disposable Personal Income | Monthly   | Billions |

## Housing Market

### Home Prices

| Series ID     | Description                        | Frequency | Units              |
| ------------- | ---------------------------------- | --------- | ------------------ |
| **CSUSHPISA** | Case-Shiller National Index        | Monthly   | Index Jan 2000=100 |
| **MSPUS**     | Median Sales Price                 | Quarterly | Dollars            |
| **ASPUS**     | Average Sales Price                | Quarterly | Dollars            |
| **USSTHPI**   | All-Transactions House Price Index | Quarterly | Index 1980Q1=100   |

### Housing Activity

| Series ID         | Description              | Frequency | Units     |
| ----------------- | ------------------------ | --------- | --------- |
| **HOUST**         | Housing Starts           | Monthly   | Thousands |
| **PERMIT**        | Building Permits         | Monthly   | Thousands |
| **HSN1F**         | New Home Sales           | Monthly   | Thousands |
| **EXHOSLUSM495S** | Existing Home Sales      | Monthly   | Millions  |
| **MSACSR**        | Monthly Supply of Houses | Monthly   | Months    |

### Rental Market

| Series ID        | Description               | Frequency | Units             |
| ---------------- | ------------------------- | --------- | ----------------- |
| **CUUR0000SEHA** | Rent of Primary Residence | Monthly   | Index 1982-84=100 |
| **RRVRUSQ156N**  | Rental Vacancy Rate       | Quarterly | Percent           |

## Consumer & Business

### Consumer Indicators

| Series ID   | Description           | Frequency | Units               |
| ----------- | --------------------- | --------- | ------------------- |
| **UMCSENT** | Consumer Sentiment    | Monthly   | Index 1966Q1=100    |
| **RSXFS**   | Retail Sales          | Monthly   | Millions of Dollars |
| **PCE**     | Personal Consumption  | Monthly   | Billions            |
| **PSAVERT** | Personal Savings Rate | Monthly   | Percent             |
| **TOTALSA** | Vehicle Sales         | Monthly   | Millions            |

### Business Indicators

| Series ID    | Description           | Frequency | Units          |
| ------------ | --------------------- | --------- | -------------- |
| **INDPRO**   | Industrial Production | Monthly   | Index 2017=100 |
| **CAPACITY** | Capacity Utilization  | Monthly   | Percent        |
| **BUSINV**   | Business Inventories  | Monthly   | Millions       |
| **NEWORDER** | New Orders            | Monthly   | Millions       |
| **NAPMNOI**  | ISM Manufacturing PMI | Monthly   | Index          |

## International

### Exchange Rates

| Series ID    | Description           | Frequency | Units      |
| ------------ | --------------------- | --------- | ---------- |
| **DEXUSEU**  | US/Euro               | Daily     | US\$/Euro  |
| **DEXJPUS**  | Japan/US              | Daily     | Yen/US\$   |
| **DEXUSUK**  | US/UK                 | Daily     | US\$/Pound |
| **DEXCHUS**  | China/US              | Daily     | Yuan/US\$  |
| **DEXCAUS**  | Canada/US             | Daily     | CAD/US\$   |
| **DTWEXBGS** | Trade Weighted Dollar | Daily     | Index      |

### Global Indicators

| Series ID            | Description           | Frequency | Units           |
| -------------------- | --------------------- | --------- | --------------- |
| **BRENT**            | Brent Crude Oil Price | Daily     | Dollars/Barrel  |
| **DCOILWTICO**       | WTI Crude Oil         | Daily     | Dollars/Barrel  |
| **GOLDAMGBD228NLBM** | Gold Price            | Daily     | Dollars/Troy Oz |
| **DEXKOUS**          | Korea/US Exchange     | Daily     | Won/US\$        |

## Banking & Money Supply

### Money Supply

| Series ID    | Description     | Frequency | Units    |
| ------------ | --------------- | --------- | -------- |
| **M1SL**     | M1 Money Supply | Monthly   | Billions |
| **M2SL**     | M2 Money Supply | Monthly   | Billions |
| **BOGMBASE** | Monetary Base   | Monthly   | Billions |
| **VELOCITY** | Velocity of M2  | Quarterly | Ratio    |

### Banking Indicators

| Series ID          | Description     | Frequency | Units    |
| ------------------ | --------------- | --------- | -------- |
| **TOTBKCR**        | Bank Credit     | Weekly    | Billions |
| **DPSACBW027SBOG** | Deposits        | Weekly    | Billions |
| **TOTRESNS**       | Total Reserves  | Monthly   | Billions |
| **EXCSRESNS**      | Excess Reserves | Monthly   | Billions |

## Government Finance

### Federal Budget

| Series ID       | Description             | Frequency | Units    |
| --------------- | ----------------------- | --------- | -------- |
| **FYFSD**       | Federal Surplus/Deficit | Annual    | Millions |
| **GFDEBTN**     | Federal Debt Total      | Quarterly | Billions |
| **GFDEGDQ188S** | Federal Debt to GDP     | Quarterly | Percent  |
| **FYFR**        | Federal Receipts        | Annual    | Millions |
| **FYONET**      | Federal Outlays         | Annual    | Millions |

### Government Spending

| Series ID   | Description              | Frequency | Units    |
| ----------- | ------------------------ | --------- | -------- |
| **GCE**     | Government Consumption   | Quarterly | Billions |
| **FDEFX**   | Federal Defense Spending | Quarterly | Billions |
| **SLFDEFX** | State & Local Spending   | Quarterly | Billions |

## Commodities

### Energy

| Series ID      | Description            | Frequency | Units          |
| -------------- | ---------------------- | --------- | -------------- |
| **DCOILWTICO** | WTI Crude Oil          | Daily     | \$/Barrel      |
| **GASREGW**    | Regular Gasoline Price | Weekly    | \$/Gallon      |
| **DHHNGSP**    | Natural Gas Price      | Daily     | \$/Million BTU |

### Metals

| Series ID            | Description  | Frequency | Units         |
| -------------------- | ------------ | --------- | ------------- |
| **GOLDAMGBD228NLBM** | Gold Price   | Daily     | \$/Troy Oz    |
| **DSLVSMAMZDM**      | Silver Price | Daily     | \$/Troy Oz    |
| **PCOPPUSDM**        | Copper Price | Monthly   | \$/Metric Ton |

### Agriculture

| Series ID      | Description   | Frequency | Units         |
| -------------- | ------------- | --------- | ------------- |
| **PWHEATUSDM** | Wheat Price   | Monthly   | \$/Metric Ton |
| **PCORNUSDM**  | Corn Price    | Monthly   | \$/Metric Ton |
| **PSOYBUSDM**  | Soybean Price | Monthly   | \$/Metric Ton |

## Regional Data

### State Unemployment

| Pattern | Description              | Example           |
| ------- | ------------------------ | ----------------- |
| **UR**  | State unemployment rate  | CAUR (California) |
| **URN** | State unemployment (NSA) | CAURN             |

### Metro Area

| Pattern | Description        | Example          |
| ------- | ------------------ | ---------------- |
| **URN** | Metro unemployment | NYURN (New York) |
| **POP** | Metro population   | NYPOP            |

## Usage Tips

### Finding Similar Series

1. Use the base series ID to search for related data
2. Add suffixes for different frequencies or adjustments
3. Check tags for geographic or topical variations

### Common Transformations

```json theme={null}
// Year-over-year inflation
{
  "series_id": "CPIAUCSL",
  "units": "pc1"
}

// Quarterly GDP growth
{
  "series_id": "GDPC1",
  "units": "pca"
}

// Monthly change in employment
{
  "series_id": "PAYEMS",
  "units": "chg"
}
```

### Combining Series

Many analyses require multiple series:

* **Taylor Rule**: DFF, GDPPOT, GDPC1, PCEPI
* **Yield Curve**: DGS3MO, DGS2, DGS10, DGS30
* **Labor Market Health**: UNRATE, PAYEMS, CIVPART, CES0500000003

## Related Resources

<CardGroup>
  <Card title="Search for Series" icon="magnifying-glass" href="/api-reference/fred-search">
    Find specific series by keywords
  </Card>

  <Card title="Browse Categories" icon="folder-tree" href="/api-reference/fred-browse">
    Explore available categories
  </Card>

  <Card title="Get Series Data" icon="chart-line" href="/api-reference/fred-get-series">
    Retrieve time series data
  </Card>

  <Card title="Data Transformations" icon="arrow-right-arrow-left" href="/resources/data-transformations">
    Transform and analyze data
  </Card>
</CardGroup>


# Data Transformations Reference
Source: https://fred-mcp-server.amorelli.tech/resources/data-transformations

Complete reference for FRED data transformations

# Data Transformations Reference

Quick reference guide for all available FRED data transformations.

## Transformation Codes

| Code | Name         | Formula                 | Use Case      |
| ---- | ------------ | ----------------------- | ------------- |
| lin  | Levels       | x\_t                    | Raw values    |
| chg  | Change       | x\_t - x\_              | Period change |
| ch1  | Change YoY   | x\_t - x\_              | Annual change |
| pch  | % Change     | ((x\_t/x\_)-1)\*100     | Growth rate   |
| pc1  | % Change YoY | ((x\_t/x\_)-1)\*100     | Annual growth |
| pca  | Annual Rate  | (((x\_t/x\_)^n)-1)\*100 | Annualized    |
| cch  | Log Change   | (ln(x\_t)-ln(x\_))\*100 | Log returns   |
| cca  | Log Annual   | (ln(x\_t)-ln(x\_))\*100 | Annual log    |
| log  | Natural Log  | ln(x\_t)                | Log levels    |

## Selection Guide

### By Data Type

**Flow Variables** (rates, prices):

* Use: pch, pc1, pca
* Example: Inflation, interest rates

**Stock Variables** (levels, balances):

* Use: chg, ch1
* Example: Employment, inventories

**Financial Returns**:

* Use: cch, log
* Example: Stock prices, exchange rates

## Common Mistakes

❌ **Don't:**

* Transform already-transformed series
* Mix frequencies when comparing
* Ignore seasonal adjustment

✅ **Do:**

* Check original units
* Use consistent transformations
* Document your choices

## Next Steps

<CardGroup>
  <Card title="Examples" icon="code" href="/examples/data-transformations">
    Practical examples
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/fred-get-series">
    API documentation
  </Card>
</CardGroup>


# FAQ
Source: https://fred-mcp-server.amorelli.tech/resources/faq

Frequently asked questions about FRED MCP Server

# Frequently Asked Questions

## General Questions

<AccordionGroup>
  <Accordion title="What is FRED?">
    FRED (Federal Reserve Economic Data) is a database of over 800,000 economic time series maintained by the Federal Reserve Bank of St. Louis. It provides free access to economic data from U.S. and international sources.
  </Accordion>

  <Accordion title="What is MCP?">
    Model Context Protocol (MCP) is an open standard that enables AI assistants to connect to external data sources and tools. The FRED MCP Server implements this protocol to provide AI assistants with access to FRED's economic data.
  </Accordion>

  <Accordion title="Is FRED data free?">
    Yes! FRED data is completely free for research, education, and personal use. You just need to register for a free API key. Commercial use may require permission.
  </Accordion>

  <Accordion title="Do I need programming experience?">
    No! When using the MCP server with AI assistants like Claude, you can request economic data using natural language. The AI assistant handles the technical details.
  </Accordion>
</AccordionGroup>

## API and Access

<AccordionGroup>
  <Accordion title="How do I get an API key?">
    1. Visit [FRED API Registration](https://fredaccount.stlouisfed.org/apikeys)
    2. Create a free account
    3. Request an API key (instant approval)
    4. Add key to your configuration

    See the [Authentication guide](/core-concepts/authentication) for details.
  </Accordion>

  <Accordion title="What are the rate limits?">
    * 120 requests per minute (general)
    * 40 requests per minute (series observations)
    * Daily limits vary by account

    The MCP server handles rate limiting automatically with retries.
  </Accordion>

  <Accordion title="Can I use this commercially?">
    The FRED MCP Server is open source (AGPL-3.0). For commercial use of FRED data, review [FRED's terms](https://fred.stlouisfed.org/docs/api/terms_of_use.html) or contact the FRED team.
  </Accordion>
</AccordionGroup>

## Data Questions

<AccordionGroup>
  <Accordion title="How current is the data?">
    FRED data is updated as soon as source agencies release it. Update frequencies vary:

    * Daily: Interest rates, stock prices
    * Weekly: Jobless claims
    * Monthly: Employment, inflation
    * Quarterly: GDP
  </Accordion>

  <Accordion title="How far back does data go?">
    It varies by series. Some series date back to the 1800s, while others are more recent. Check each series' `observation_start` field.
  </Accordion>

  <Accordion title="What does 'seasonally adjusted' mean?">
    Seasonally adjusted (SA) data has regular seasonal patterns removed, making it easier to identify underlying trends. Use SA data for comparing across different months or analyzing trends.
  </Accordion>

  <Accordion title="Why are there multiple inflation measures?">
    Different measures serve different purposes:

    * **CPI**: Consumer prices, used for cost-of-living adjustments
    * **PCE**: Personal consumption expenditure, Fed's preferred measure
    * **PPI**: Producer prices, early indicator of consumer inflation
    * **Core**: Excludes volatile food and energy prices
  </Accordion>
</AccordionGroup>

## Technical Questions

<AccordionGroup>
  <Accordion title="Which AI assistants are supported?">
    Any MCP-compatible AI assistant, including:

    * Claude Desktop
    * Other MCP-enabled clients

    See the [Installation guide](/installation) for setup instructions.
  </Accordion>

  <Accordion title="Can I use this without an AI assistant?">
    The MCP server is designed for AI assistants, but you can access FRED data directly through:

    * FRED website
    * FRED API
    * FRED add-ins for Excel, R, Python
  </Accordion>

  <Accordion title="How do I update the server?">
    ```bash theme={null}
    npm update -g fred-mcp-server
    ```

    Then restart your MCP client.
  </Accordion>

  <Accordion title="Where are logs stored?">
    Logs depend on your MCP client. For Claude Desktop:

    * macOS: `~/Library/Logs/Claude/`
    * Windows: `%APPDATA%\Claude\logs\`
  </Accordion>
</AccordionGroup>

## Common Issues

<AccordionGroup>
  <Accordion title="Why am I getting authentication errors?">
    Common causes:

    * API key not set in environment
    * Typo in API key
    * API key revoked
    * Server not restarted after config change

    See [Troubleshooting](/resources/troubleshooting) for solutions.
  </Accordion>

  <Accordion title="Why is my series search returning no results?">
    Try:

    * Broader search terms
    * Checking series ID spelling
    * Using `fred_browse` instead
    * Removing restrictive tags
  </Accordion>

  <Accordion title="Why is data missing for certain dates?">
    Possible reasons:

    * Weekends/holidays (daily data)
    * Series discontinued
    * Data not yet released
    * Gaps in source data
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Which series should I use?">
    Popular starting points:

    * **UNRATE**: Unemployment rate
    * **CPIAUCSL**: Inflation (CPI)
    * **GDP**: Economic output
    * **DFF**: Fed funds rate
    * **SP500**: Stock market

    See [Common Series](/resources/common-series) for more.
  </Accordion>

  <Accordion title="How should I cite FRED data?">
    Include:

    * Series source (e.g., "U.S. Bureau of Labor Statistics")
    * "retrieved from FRED, Federal Reserve Bank of St. Louis"
    * Series URL
    * Access date
  </Accordion>

  <Accordion title="Should I use SA or NSA data?">
    * **SA (Seasonally Adjusted)**: For trend analysis and comparisons across months
    * **NSA (Not Seasonally Adjusted)**: For understanding actual seasonal patterns

    Most analysis uses SA data.
  </Accordion>
</AccordionGroup>

## Still Need Help?

<CardGroup>
  <Card title="Troubleshooting" icon="wrench" href="/resources/troubleshooting">
    Solve common problems
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/stefanoamorelli/fred-mcp-server/issues">
    Report bugs or request features
  </Card>

  <Card title="FRED Support" icon="circle-info" href="https://fred.stlouisfed.org/contactus">
    Contact FRED team
  </Card>

  <Card title="Documentation" icon="book" href="/introduction">
    Browse full documentation
  </Card>
</CardGroup>


# FRED Series Guide
Source: https://fred-mcp-server.amorelli.tech/resources/fred-series-guide

Comprehensive guide to understanding and finding FRED series

# FRED Series Guide

Navigate FRED's vast collection of economic data series with this comprehensive reference guide.

## Series ID Structure

### Common Patterns

FRED series IDs follow recognizable patterns:

| Pattern           | Example    | Description            |
| ----------------- | ---------- | ---------------------- |
| Indicator name    | GDP, CPI   | Simple acronyms        |
| Geographic prefix | CAUR, NYUR | State code + indicator |
| Frequency suffix  | UNRATEM    | M=Monthly, Q=Quarterly |
| Adjustment suffix | GDPC1      | C=Chained, SA implied  |

## Major Categories

### National Accounts

GDP and related series:

* **GDP**: Gross Domestic Product
* **GDPC1**: Real GDP
* **GDPDEF**: GDP Deflator
* **PCE**: Personal Consumption
* **GPDI**: Gross Private Investment
* **GCE**: Government Consumption

### Employment

Labor market indicators:

* **UNRATE**: Unemployment Rate (SA)
* **PAYEMS**: Total Nonfarm Payrolls (SA)
* **CIVPART**: Labor Force Participation
* **ICSA**: Initial Jobless Claims
* **JO TS JOL**: Job Openings

### Prices

Inflation measures:

* **CPIAUCSL**: CPI All Items (SA)
* **CPILFESL**: Core CPI (SA)
* **PCEPI**: PCE Price Index
* **PCEPILFE**: Core PCE
* **PPIACO**: Producer Price Index

## Next Steps

<CardGroup>
  <Card title="Common Series" icon="star" href="/resources/common-series">
    Most popular indicators
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/overview">
    Search and retrieve data
  </Card>
</CardGroup>


# Troubleshooting
Source: https://fred-mcp-server.amorelli.tech/resources/troubleshooting

Solutions to common issues with FRED MCP Server

# Troubleshooting Guide

Solutions to common problems when using the FRED MCP Server.

## Authentication Issues

### API Key Not Found

**Symptoms:** "Bad Request. The value for variable api\_key is not registered."

**Solutions:**

<Steps>
  <Step title="Verify API Key">
    Check that your API key is exactly 32 characters
  </Step>

  <Step title="Check Environment Variable">
    Ensure `FRED_API_KEY` is set correctly
  </Step>

  <Step title="Restart Server">
    Restart the MCP server after config changes
  </Step>

  <Step title="Test Key">
    Try the key directly in a browser:

    ```
    https://api.stlouisfed.org/fred/series?series_id=GDP&api_key=YOUR_KEY
    ```
  </Step>
</Steps>

## Rate Limiting

### Too Many Requests (429)

**Symptoms:** "Too many requests" error

**Solutions:**

* Wait 60 seconds before retrying
* Reduce request frequency
* Use date ranges to limit data
* Plan queries to avoid redundant requests

## Data Issues

### Series Not Found (404)

**Symptoms:** "Bad Request. The series does not exist."

**Solutions:**

* Verify series ID spelling
* Check if series has been discontinued
* Search for alternative series
* Use `fred_search` to find correct ID

### Empty Results

**Symptoms:** No data returned

**Solutions:**

* Check date range is valid
* Verify series has data for requested period
* Try broader date range
* Check if series is vintage/discontinued

## Connection Issues

### Server Won't Start

**Symptoms:** MCP server fails to launch

**Solutions:**

<AccordionGroup>
  <Accordion title="Check Node.js">
    Ensure Node.js v16+ is installed:

    ```bash theme={null}
    node --version
    ```
  </Accordion>

  <Accordion title="Reinstall Package">
    ```bash theme={null}
    npm uninstall -g fred-mcp-server
    npm install -g fred-mcp-server
    ```
  </Accordion>

  <Accordion title="Check Permissions">
    Ensure execute permissions:

    ```bash theme={null}
    chmod +x $(which fred-mcp-server)
    ```
  </Accordion>

  <Accordion title="Review Logs">
    Check error messages in console output
  </Accordion>
</AccordionGroup>

## Performance Issues

### Slow Requests

**Symptoms:** Requests take too long

**Solutions:**

* Limit date ranges
* Reduce result limits
* Use specific series IDs
* Plan queries to minimize API calls

## Getting Help

<CardGroup>
  <Card title="GitHub Issues" icon="github" href="https://github.com/stefanoamorelli/fred-mcp-server/issues">
    Report bugs and request features
  </Card>

  <Card title="FRED API Docs" icon="book" href="https://fred.stlouisfed.org/docs/api/">
    Official FRED API documentation
  </Card>

  <Card title="FAQ" icon="circle-question" href="/resources/faq">
    Frequently asked questions
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration">
    Setup guide
  </Card>
</CardGroup>


# Academic Research
Source: https://fred-mcp-server.amorelli.tech/use-cases/academic-research

Using FRED for academic research and econometric analysis

# Academic Research

FRED provides comprehensive data for economic research, econometric modeling, and academic publications.

## Research Applications

<CardGroup>
  <Card title="Econometric Analysis" icon="chart-mixed">
    Time series modeling, regression analysis, causality testing
  </Card>

  <Card title="Policy Evaluation" icon="gavel">
    Impact studies, difference-in-differences, event studies
  </Card>

  <Card title="Forecasting" icon="crystal-ball">
    Prediction models, nowcasting, scenario analysis
  </Card>

  <Card title="Historical Analysis" icon="clock-rotate-left">
    Long-run trends, structural breaks, regime changes
  </Card>
</CardGroup>

## Data Quality

### Vintage Data

Access historical data snapshots for real-time analysis:

```javascript theme={null}
{
  "series_id": "GDP",
  "realtime_start": "2020-01-01",
  "realtime_end": "2020-01-01"
}
```

## Citation

Always cite FRED and original data sources in academic work.

## Next Steps

<CardGroup>
  <Card title="Examples" icon="code" href="/examples/time-series-analysis">
    Analysis techniques
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/overview">
    Complete documentation
  </Card>
</CardGroup>


# Economic Analysis
Source: https://fred-mcp-server.amorelli.tech/use-cases/economic-analysis

Using FRED for comprehensive economic analysis and research

# Economic Analysis Use Case

Leverage FRED MCP Server for comprehensive economic analysis, from macroeconomic forecasting to sectoral performance evaluation.

## Overview

Economic analysts use FRED data to:

* Monitor current economic conditions
* Analyze historical trends
* Identify relationships between indicators
* Support forecasting and projections
* Evaluate policy impacts

## Macroeconomic Analysis

### Business Cycle Analysis

Track key indicators across the cycle:

<Steps>
  <Step title="Leading Indicators">
    ```javascript theme={null}
    // Building permits
    { "series_id": "PERMIT" }

    // Initial jobless claims
    { "series_id": "ICSA" }

    // Yield curve spread
    { "series_id": "T10Y2Y" }

    // Consumer expectations
    { "series_id": "UMCSENT" }
    ```
  </Step>

  <Step title="Coincident Indicators">
    ```javascript theme={null}
    // GDP
    { "series_id": "GDP" }

    // Employment
    { "series_id": "PAYEMS" }

    // Industrial production
    { "series_id": "INDPRO" }

    // Retail sales
    { "series_id": "RSXFS" }
    ```
  </Step>

  <Step title="Lagging Indicators">
    ```javascript theme={null}
    // Unemployment
    { "series_id": "UNRATE" }

    // Unit labor costs
    { "series_id": "ULCNFB" }

    // Consumer credit
    { "series_id": "TOTALSL" }
    ```
  </Step>
</Steps>

### GDP Decomposition

Analyze sources of growth:

```javascript theme={null}
// Total GDP
const gdp = {
  "series_id": "GDP",
  "observation_start": "2020-Q1",
  "units": "pca"
};

// Components
const components = {
  consumption: "PCEC",      // Personal consumption (68%)
  investment: "GPDI",       // Gross private investment (17%)
  government: "GCE",        // Government spending (17%)
  net_exports: "NETEXP"     // Exports - Imports
};
```

<Tip>
  GDP = C + I + G + (X - M)

  Track component contributions to identify growth drivers
</Tip>

## Inflation Analysis

### Multiple Measures

Compare different inflation indicators:

<Tabs>
  <Tab title="Consumer Prices">
    ```javascript theme={null}
    // Headline CPI
    {
      "series_id": "CPIAUCSL",
      "units": "pc1"
    }

    // Core CPI (ex food & energy)
    {
      "series_id": "CPILFESL",
      "units": "pc1"
    }

    // Services CPI
    {
      "series_id": "CUSR0000SAS",
      "units": "pc1"
    }

    // Goods CPI
    {
      "series_id": "CUUR0000SAC",
      "units": "pc1"
    }
    ```
  </Tab>

  <Tab title="Producer Prices">
    ```javascript theme={null}
    // Headline PPI
    {
      "series_id": "PPIACO",
      "units": "pc1"
    }

    // Core PPI
    {
      "series_id": "PPILFE",
      "units": "pc1"
    }
    ```
  </Tab>

  <Tab title="PCE Deflator">
    ```javascript theme={null}
    // PCE Price Index (Fed's preferred)
    {
      "series_id": "PCEPI",
      "units": "pc1"
    }

    // Core PCE
    {
      "series_id": "PCEPILFE",
      "units": "pc1"
    }
    ```
  </Tab>

  <Tab title="Import/Export Prices">
    ```javascript theme={null}
    // Import prices
    {
      "series_id": "IR",
      "units": "pc1"
    }

    // Export prices
    {
      "series_id": "IQ",
      "units": "pc1"
    }
    ```
  </Tab>
</Tabs>

### Inflation Expectations

Monitor forward-looking indicators:

```javascript theme={null}
// University of Michigan 1-year ahead
{
  "series_id": "MICH",
  "observation_start": "2020-01-01"
}

// 5-year breakeven rate
{
  "series_id": "T5YIE",
  "observation_start": "2020-01-01"
}

// 10-year breakeven rate
{
  "series_id": "T10YIE",
  "observation_start": "2020-01-01"
}
```

## Labor Market Analysis

### Employment Dynamics

```javascript theme={null}
// Comprehensive labor market dashboard
const labor_dashboard = {
  // Headline indicators
  unemployment: "UNRATE",
  payrolls: "PAYEMS",
  participation: "CIVPART",

  // Broader measures
  u6_rate: "U6RATE",
  employment_ratio: "EMRATIO",
  part_time_economic: "LNS12032194",

  // Flows
  initial_claims: "ICSA",
  continuing_claims: "CCSA",
  job_openings: "JTSJOL",
  quits: "JTSQUL",

  // Wages
  avg_hourly_earnings: "CES0500000003",
  real_earnings: "CES0500000030",
  unit_labor_costs: "ULCNFB"
};
```

### Sectoral Employment

Track employment by industry:

<CardGroup>
  <Card title="Manufacturing" icon="industry">
    ```javascript theme={null}
    { "series_id": "MANEMP" }
    ```
  </Card>

  <Card title="Construction" icon="helmet-safety">
    ```javascript theme={null}
    { "series_id": "USCONS" }
    ```
  </Card>

  <Card title="Retail Trade" icon="cart-shopping">
    ```javascript theme={null}
    { "series_id": "USTRADE" }
    ```
  </Card>

  <Card title="Healthcare" icon="heart-pulse">
    ```javascript theme={null}
    { "series_id": "CES6500000001" }
    ```
  </Card>

  <Card title="Professional Services" icon="briefcase">
    ```javascript theme={null}
    { "series_id": "USPBS" }
    ```
  </Card>

  <Card title="Leisure & Hospitality" icon="utensils">
    ```javascript theme={null}
    { "series_id": "CES7000000001" }
    ```
  </Card>
</CardGroup>

## Financial Conditions

### Interest Rate Analysis

```javascript theme={null}
// Yield curve
const yield_curve = {
  one_month: "DGS1MO",
  three_month: "DGS3MO",
  six_month: "DGS6MO",
  one_year: "DGS1",
  two_year: "DGS2",
  five_year: "DGS5",
  ten_year: "DGS10",
  thirty_year: "DGS30"
};

// Spreads
const spreads = {
  ten_two: "T10Y2Y",
  ten_three_month: "T10Y3M",
  bbb_treasury: "BAMLC0A4CBBB"
};
```

### Financial Stress Indicators

```javascript theme={null}
// St. Louis Fed Financial Stress Index
{
  "series_id": "STLFSI2",
  "observation_start": "2020-01-01"
}

// TED Spread
{
  "series_id": "TEDRATE",
  "observation_start": "2020-01-01"
}

// VIX (market volatility)
{
  "series_id": "VIXCLS",
  "observation_start": "2020-01-01"
}
```

## Sectoral Analysis

### Housing Market

```javascript theme={null}
const housing_metrics = {
  // Supply
  starts: "HOUST",
  permits: "PERMIT",
  under_construction: "UNDCONTSA",

  // Demand
  existing_sales: "EXHOSLUSM495S",
  new_sales: "HSN1F",

  // Prices
  case_shiller: "CSUSHPISA",
  fhfa_index: "USSTHPI",
  median_price: "MSPUS",

  // Affordability
  mortgage_rate: "MORTGAGE30US",
  affordability_index: "FIXHAI"
};
```

### Manufacturing Sector

```javascript theme={null}
// Production
{
  "series_id": "IPMAN",
  "observation_start": "2020-01-01",
  "units": "pc1"
}

// Orders
{
  "series_id": "AMTMNO",
  "observation_start": "2020-01-01"
}

// Capacity utilization
{
  "series_id": "MCU",
  "observation_start": "2020-01-01"
}

// PMI
{
  "series_id": "MANEMP",
  "observation_start": "2020-01-01"
}
```

## Regional Analysis

### State Comparisons

```javascript theme={null}
// Compare unemployment across states
const states = ["CA", "TX", "NY", "FL", "IL"];

states.forEach(state => {
  fred_get_series({
    series_id: `${state}UR`,
    observation_start: "2020-01-01"
  });
});

// State GDP
states.forEach(state => {
  fred_get_series({
    series_id: `${state}NGSP`,
    observation_start: "2020-Q1"
  });
});
```

### Metro Area Analysis

```javascript theme={null}
// Major metro unemployment rates
const metros = {
  nyc: "LAUMT364190",
  la: "LAUMT064910",
  chicago: "LAUMT121410",
  dallas: "LAUMT481910",
  houston: "LAUMT482610"
};
```

## Recession Analysis

### NBER Dating

```javascript theme={null}
// Official recession indicator
{
  "series_id": "USREC",
  "observation_start": "2000-01-01"
}

// Sahm Rule Recession Indicator
{
  "series_id": "SAHMREALTIME",
  "observation_start": "2000-01-01"
}
```

### Recession Depth and Duration

<Steps>
  <Step title="Identify Peak">
    Find pre-recession highs in key indicators
  </Step>

  <Step title="Track Trough">
    Identify lowest points during recession
  </Step>

  <Step title="Measure Recovery">
    Calculate time to return to pre-recession levels
  </Step>

  <Step title="Compare Recessions">
    Analyze differences in depth, duration, and recovery shape
  </Step>
</Steps>

## International Comparisons

### Global Indicators

```javascript theme={null}
// OECD data
const global = {
  // Composite leading indicators
  us_cli: "USALOLITONOSTSAM",
  oecd_cli: "USALOLITONOSTSAM",

  // GDP
  g7_gdp: "NAEXKP01",
  china_gdp: "CHNNGDP",
  eu_gdp: "CLVMNACSCAB1GQEU272020",

  // Trade
  global_trade: "WLDXTIMVA"
};
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use Multiple Indicators">
    Don't rely on single metrics. Cross-validate with complementary series.
  </Accordion>

  <Accordion title="Check Data Revisions">
    Economic data undergoes revisions. Use vintage data for historical analysis.
  </Accordion>

  <Accordion title="Understand Seasonal Patterns">
    Use SA data for trends, NSA for actual seasonal patterns.
  </Accordion>

  <Accordion title="Consider Lead Times">
    Account for reporting lags and indicator relationships.
  </Accordion>

  <Accordion title="Document Methodology">
    Record transformation choices and analysis assumptions.
  </Accordion>
</AccordionGroup>

## Analysis Workflow

<Steps>
  <Step title="Define Question">
    Clearly state what you're analyzing
  </Step>

  <Step title="Identify Indicators">
    Select relevant series for your analysis
  </Step>

  <Step title="Gather Data">
    Retrieve series with appropriate transformations
  </Step>

  <Step title="Analyze Trends">
    Look for patterns, correlations, and anomalies
  </Step>

  <Step title="Validate Findings">
    Cross-check with alternative indicators
  </Step>

  <Step title="Document Results">
    Record methodology and conclusions
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Financial Research" icon="chart-candlestick" href="/use-cases/financial-research">
    Markets and asset analysis
  </Card>

  <Card title="Policy Analysis" icon="landmark" href="/use-cases/policy-analysis">
    Policy impact evaluation
  </Card>

  <Card title="Examples" icon="code" href="/examples/economic-indicators">
    Practical code examples
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/overview">
    Tool documentation
  </Card>
</CardGroup>


# Financial Research
Source: https://fred-mcp-server.amorelli.tech/use-cases/financial-research

Using FRED for financial markets analysis and investment research

# Financial Research Use Case

Use FRED MCP Server for financial markets analysis, portfolio research, and investment strategy development.

## Market Analysis

### Equity Markets

```javascript theme={null}
// Major indices
const indices = {
  sp500: "SP500",
  dow: "DJIA",
  nasdaq: "NASDAQCOM",
  russell2000: "RU2000PR",
  wilshire5000: "WILL5000PRFC"
};
```

### Fixed Income

```javascript theme={null}
// Treasury yields
const treasuries = {
  three_month: "DGS3MO",
  two_year: "DGS2",
  five_year: "DGS5",
  ten_year: "DGS10",
  thirty_year: "DGS30"
};

// Corporate spreads
const spreads = {
  aaa_corporate: "DAAA",
  baa_corporate: "DBAA",
  high_yield: "BAMLH0A0HYM2"
};
```

### Exchange Rates

```javascript theme={null}
// Major currencies
const currencies = {
  euro: "DEXUSEU",
  pound: "DEXUSUK",
  yen: "DEXJPUS",
  yuan: "DEXCHUS",
  swiss_franc: "DEXSZUS"
};
```

## Risk Analysis

### Volatility Indicators

```javascript theme={null}
// VIX
{ "series_id": "VIXCLS" }

// Credit spreads
{ "series_id": "BAMLH0A0HYM2" }

// Financial stress
{ "series_id": "STLFSI2" }
```

## Asset Allocation

### Economic Regime Analysis

Track indicators to inform asset allocation decisions based on economic conditions.

<CardGroup>
  <Card title="Growth" icon="chart-line-up">
    GDP, Employment, Industrial Production
  </Card>

  <Card title="Inflation" icon="fire">
    CPI, PCE, Breakeven Rates
  </Card>

  <Card title="Policy" icon="landmark">
    Fed Funds Rate, Balance Sheet
  </Card>

  <Card title="Sentiment" icon="face-smile">
    Consumer Confidence, Business Surveys
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Market Monitoring" icon="display" href="/use-cases/market-monitoring">
    Real-time market tracking
  </Card>

  <Card title="Examples" icon="code" href="/examples/basic-usage">
    Code examples
  </Card>
</CardGroup>


# Market Monitoring
Source: https://fred-mcp-server.amorelli.tech/use-cases/market-monitoring

Real-time tracking of markets and economic indicators

# Market Monitoring

Build monitoring systems and dashboards using FRED for real-time economic and market surveillance.

## Dashboard Components

### Key Indicators

```javascript theme={null}
const dashboard = {
  // Markets
  sp500: "SP500",
  vix: "VIXCLS",
  ten_year: "DGS10",

  // Economy  
  unemployment: "UNRATE",
  inflation: "CPIAUCSL",
  gdp: "GDP",

  // Policy
  fed_funds: "DFF",
  balance_sheet: "WALCL"
};
```

## Alert Systems

Monitor for significant changes:

* Unemployment rate changes > 0.3%
* Inflation exceeds target ranges
* Yield curve inversions
* Market volatility spikes

## Update Frequencies

| Series          | Update Frequency | Release Time             |
| --------------- | ---------------- | ------------------------ |
| Fed Funds       | Daily            | Next day                 |
| Treasury Yields | Daily            | Next day                 |
| Initial Claims  | Weekly           | Thursday 8:30 AM ET      |
| CPI             | Monthly          | \~13th, 8:30 AM ET       |
| Employment      | Monthly          | First Friday, 8:30 AM ET |
| GDP             | Quarterly        | \~30 days after quarter  |

## Next Steps

<CardGroup>
  <Card title="Advanced Queries" icon="magnifying-glass-chart" href="/examples/advanced-queries">
    Efficient data retrieval
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/overview">
    Tool documentation
  </Card>
</CardGroup>


# Policy Analysis
Source: https://fred-mcp-server.amorelli.tech/use-cases/policy-analysis

Evaluating economic policy impacts using FRED data

# Policy Analysis

Use FRED to evaluate policy effectiveness, analyze interventions, and support evidence-based policymaking.

## Monetary Policy Analysis

### Federal Reserve Actions

```javascript theme={null}
// Policy rate
{ "series_id": "DFF" }

// Balance sheet
{ "series_id": "WALCL" }

// Reserve balances
{ "series_id": "WRESBAL" }
```

### Policy Transmission

Track how policy changes affect the economy through various channels.

## Fiscal Policy

### Government Spending

```javascript theme={null}
// Federal spending
{ "series_id": "FGEXPND" }

// Receipts
{ "series_id": "FGRECPT" }

// Deficit
{ "series_id": "FYFSD" }

// Debt
{ "series_id": "GFDEBTN" }
```

## Impact Evaluation

<Steps>
  <Step title="Identify Policy Change">
    Mark exact timing of policy implementation
  </Step>

  <Step title="Select Indicators">
    Choose relevant outcome measures
  </Step>

  <Step title="Analyze Before/After">
    Compare periods pre and post intervention
  </Step>

  <Step title="Control for Confounders">
    Account for other simultaneous changes
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Economic Analysis" icon="chart-mixed" href="/use-cases/economic-analysis">
    Comprehensive analysis workflows
  </Card>

  <Card title="Examples" icon="code" href="/examples/economic-indicators">
    Indicator examples
  </Card>
</CardGroup>