Skip to main content

​
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

​
Data Discovery & Navigation

The fred_browse and fred_search tools work together to help you discover relevant economic data:
Navigate through hierarchical categories like:
  • Money, Banking & Finance
  • Population, Employment & Labor Markets
  • Production & Business Activity
  • International Data
Find series using:
  • Full-text search across titles and descriptions
  • Tag-based filtering (e.g., “gdp”, “monthly”, “seasonally-adjusted”)
  • Combined search criteria
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:
  • Historical observations dating back decades
  • Real-time data updates
  • Custom date ranges
  • Vintage data for point-in-time analysis
  • Growth rates and percent changes
  • Year-over-year comparisons
  • Logarithmic transformations
  • Moving averages
  • Frequency conversions
  • 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:
​
limit
number
default:"25"
Maximum number of results to return. Range varies by tool:
  • Search: 1-1000
  • Browse: 1-1000
  • Series: 1-100000
​
offset
number
default:"0"
Number of results to skip for pagination. Useful for retrieving large result sets.
​
sort_order
string
default:"asc"
Sort order for results:
  • asc: Ascending order
  • desc: Descending order
​
order_by
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 CodeDescriptionSolution
INVALID_API_KEYAPI key is invalid or missingCheck your FRED API key configuration
SERIES_NOT_FOUNDRequested series ID doesn’t existVerify the series ID or search for alternatives
RATE_LIMIT_EXCEEDEDToo many requestsWait and retry, or reduce request frequency
INVALID_DATE_RANGEDate parameters are invalidUse YYYY-MM-DD format and ensure start < end
TRANSFORMATION_ERRORCannot apply requested transformationCheck if transformation is valid for the series

​
Best Practices

1

Start with Search or Browse

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

Use Appropriate Limits

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

Respect Rate Limits

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

Handle Errors Gracefully

Always check for error responses and have fallback strategies.

​
Tool Comparison

Featurefred_browsefred_searchfred_get_series
PurposeNavigate catalogFind specific seriesRetrieve data
InputCategory/Release IDsKeywords/TagsSeries ID
OutputLists of categories/seriesMatching seriesTime series data
Best ForExploring available dataFinding known indicatorsGetting actual values
Pagination✅ Yes✅ Yes✅ Yes
FilteringBasicAdvancedN/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
});

​
Next Steps

fred_browse

Browse tool reference

fred_search

Search tool reference

fred_get_series

Series tool reference