nimar2/fred-mcp-server

FRED MCP Server

An MCP (Model Context Protocol) server that provides AI assistants with access to the Federal Reserve Economic Data (FRED) API. Access over 800,000+ economic time series including GDP, unemployment, inflation, interest rates, and more.

Features

This server exposes three powerful tools:

Prerequisites

1. Python >= 3.10
2. FRED API Key - Get one free at: https://fred.stlouisfed.org/docs/api/api_key.html

Installation

# Clone the repository
git clone https://github.com/nimar2/fred-mcp-server.git
cd fred-mcp-server

# Create virtual environment (recommended)
python3.12 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "fred": {
      "command": "python",
      "args": ["/absolute/path/to/fred-mcp-server/server.py"],
      "env": {
        "FRED_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code

claude mcp add fred -s user -- python /path/to/fred-mcp-server/server.py -e FRED_API_KEY=your-api-key

Or add to ~/.claude/settings.json:

{
  "mcpServers": {
    "fred": {
      "command": "python3.12",
      "args": ["/absolute/path/to/fred-mcp-server/server.py"],
      "env": {
        "FRED_API_KEY": "your-api-key-here"
      }
    }
  }
}

Tools Reference

fred_search

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

Parameters:

Examples:

# Search for GDP series
search_text: "gross domestic product"
limit: 10

# Search with tags
search_text: "money supply"
tag_names: "usa;m2"
order_by: "popularity"

# Filter by frequency
search_text: "inflation"
filter_variable: "frequency"
filter_value: "Monthly"

fred_get_series

Retrieve observation data for any FRED series with optional transformations.

Parameters:

Units Transformations:

• lin - Levels (no transformation)
• chg - Change from previous period
• ch1 - Change from year ago
• pch - Percent change
• 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

Frequency Aggregation:

• d (Daily), w (Weekly), bw (Biweekly), m (Monthly), q (Quarterly), sa (Semiannual), a (Annual)

Examples:

# Get unemployment rate
series_id: "UNRATE"

# Get GDP with date range
series_id: "GDP"
observation_start: "2020-01-01"
observation_end: "2024-01-01"

# Get percent change in CPI
series_id: "CPIAUCSL"
units: "pch"

# Aggregate daily Fed Funds to monthly
series_id: "DFF"
frequency: "m"
aggregation_method: "avg"

fred_browse

Browse FRED's complete catalog through categories, releases, or sources.

Parameters:

Examples:

# Browse root categories
browse_type: "categories"

# Browse Money, Banking & Finance subcategories
browse_type: "categories"
category_id: 32991

# List all releases
browse_type: "releases"
order_by: "name"

# List all data sources
browse_type: "sources"

# Get series in GDP release
browse_type: "release_series"
release_id: 53

Common Series IDs

Development

# Run tests
pytest test_server.py -v

# Test with MCP Inspector
FRED_API_KEY=your-key mcp dev server.py

API Documentation

• FRED API Overview
• Series Search
• Series Observations
• Categories
• Releases
• Sources

License

MIT