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

fred_browse

Navigate FRED’s catalog through categories, releases, and sources

fred_search

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

fred_get_series

Retrieve time series data with transformations and aggregations

Tool Capabilities

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

Browse by Category

Navigate through hierarchical categories like:

Money, Banking & Finance
Population, Employment & Labor Markets
Production & Business Activity
International Data

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

Filter by Attributes

Narrow results by:

Frequency (daily, weekly, monthly, quarterly, annual)
Units (levels, percent change, index)
Seasonal adjustment status
Geographic region

Data Retrieval & Transformation

The fred_get_series tool provides comprehensive data access:

Time Series Data

Historical observations dating back decades
Real-time data updates
Custom date ranges
Vintage data for point-in-time analysis

Built-in Transformations

Growth rates and percent changes
Year-over-year comparisons
Logarithmic transformations
Moving averages
Frequency conversions

Aggregation Methods

Average over periods
Sum of values
End-of-period observations
Custom sampling frequencies

Response Formats

All tools return structured JSON responses:

Success Response Structure

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

Error Response Structure

{
  "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:

number

default:"25"

Maximum number of results to return. Range varies by tool:

Search: 1-1000
Browse: 1-1000
Series: 1-100000

number

default:"0"

Number of results to skip for pagination. Useful for retrieving large result sets.

string

default:"asc"

Sort order for results:

asc: Ascending order
desc: Descending order

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

Rate Limits

FRED API has rate limits to ensure fair usage:

120 requests per minute for general API calls
40 requests per minute for series observations

The server automatically handles rate limiting with:

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

Data Freshness

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

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

Start with Search or Browse

Don’t guess series IDs. Use fred_search or fred_browse to discover available data.

Use Appropriate Limits

Start with smaller limits and increase as needed. Large requests may timeout.

Respect Rate Limits

Plan queries carefully and respect FRED API rate limits. Review FRED’s terms of use.

Handle Errors Gracefully

Always check for error responses and have fallback strategies.

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

// 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
});

# 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'
})

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

Next Steps

fred_browse

Browse tool reference

fred_search

Search tool reference

fred_get_series

Series tool reference

API Tools

API Overview

API Reference Overview

Available Tools

fred_browse

fred_search

fred_get_series

Tool Capabilities

Data Discovery & Navigation

Data Retrieval & Transformation

Response Formats

Success Response Structure

Error Response Structure

Common Parameters

Rate Limits

Data Freshness

Error Handling

Best Practices

Tool Comparison

Integration Examples

Next Steps

fred_browse

fred_search

fred_get_series

​API Reference Overview

​Available Tools

fred_browse

fred_search

fred_get_series

​Tool Capabilities

​Data Discovery & Navigation

​Data Retrieval & Transformation

​Response Formats

​Success Response Structure

​Error Response Structure

​Common Parameters

​Rate Limits

​Data Freshness

​Error Handling

​Best Practices

​Tool Comparison

​Integration Examples

​Next Steps

fred_browse

fred_search

fred_get_series

API Reference Overview

Available Tools

Tool Capabilities

Data Discovery & Navigation

Data Retrieval & Transformation

Response Formats

Success Response Structure

Error Response Structure

Common Parameters

Rate Limits

Data Freshness

Error Handling

Best Practices

Tool Comparison

Integration Examples

Next Steps