> ## Documentation Index
> Fetch the complete documentation index at: https://fred-mcp-server.amorelli.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# API 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 cols={3}>
  <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 path="limit" type="number" default="25">
  Maximum number of results to return. Range varies by tool:

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

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

<ParamField path="sort_order" type="string" default="asc">
  Sort order for results:

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

<ParamField path="order_by" 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 cols={3}>
  <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>