fred-mcp-server

An MCP (Model Context Protocol) server that provides access to the full FRED API (Federal Reserve Economic Data), including the Maps API for regional and geographic data. Use it to search, explore, and retrieve economic data directly within Claude conversations.

Disclaimer: This project is not affiliated with, endorsed by, or connected to the Federal Reserve Bank of St. Louis or any Federal Reserve entity. It is an independent open-source tool that accesses the publicly available FRED API.

Features

• 33 tools covering all FRED API endpoints including Maps (series, categories, releases, sources, tags, maps)
• Full parameter support — no artificial limits on pagination or filtering
• Built-in rate limiting (120 requests/minute)
• Async HTTP client for efficient request handling

Requirements

• Python 3.10+
• A free FRED API key

Installation

pip install fred-mcp-server

Or with uv:

uv tool install fred-mcp-server

With Docker:

docker pull ghcr.io/floriancaro/fred-mcp-server

Or build from source:

docker build -t fred-mcp-server https://github.com/floriancaro/fred-mcp-server.git

From source:

git clone https://github.com/floriancaro/fred-mcp-server.git
cd fred-mcp-server
uv sync --dev

Configuration

After installing, configure the MCP server for your preferred client.

Claude Code (CLI)

Add the server globally (available in all projects):

claude mcp add fred -s user -e FRED_API_KEY=your-api-key-here -- fred-mcp-server

Or add it to a specific project only:

claude mcp add fred -e FRED_API_KEY=your-api-key-here -- fred-mcp-server

Verify it's connected:

claude mcp list

Claude Code (project config)

Alternatively, create a .mcp.json file in your project root:

{
  "mcpServers": {
    "fred": {
      "command": "fred-mcp-server",
      "env": {
        "FRED_API_KEY": "your-api-key-here"
      }
    }
  }
}

A .mcp.json.example file is included in the repo as a template.

Claude Desktop

Add to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fred": {
      "command": "fred-mcp-server",
      "env": {
        "FRED_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart Claude Desktop after saving.

Docker

If using the Docker image, replace the command field:

{
  "mcpServers": {
    "fred": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "FRED_API_KEY", "ghcr.io/floriancaro/fred-mcp-server"],
      "env": {
        "FRED_API_KEY": "your-api-key-here"
      }
    }
  }
}

Tools

Series

Categories

Releases

Sources

Tags

Maps

Example Prompts

Once configured, you can ask Claude things like:

• "What is the current US GDP growth rate?" (uses fred_series_search + fred_series_observations)
• "Show me the unemployment rate for the past 10 years" (uses fred_series_observations with observation_start)
• "What data releases are coming up this week?" (uses fred_releases_dates)
• "Find all series related to housing starts" (uses fred_series_search)
• "Compare regional unemployment rates across states" (uses geofred_regional_data)

Development

git clone https://github.com/floriancaro/fred-mcp-server.git
cd fred-mcp-server
uv sync --dev

# Run unit tests
uv run pytest tests/test_client.py tests/test_tools.py -v

# Run integration tests (requires FRED_API_KEY)
FRED_API_KEY=your-key uv run pytest tests/test_integration.py -v

Troubleshooting

"FRED_API_KEY environment variable is not set" Ensure the FRED_API_KEY is passed in your MCP configuration's env block, or set it in your shell environment.

Rate limiting The server limits requests to 120 per minute (matching FRED API limits). If you hit the limit, requests will automatically wait — no action needed.

Verifying the server is running

claude mcp list

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT