Federal Reserve Economic Data MCP Server

A production-grade Model Context Protocol server for FRED® economic data. Covers all 31 endpoints exposed by fred-py-api.

Features

• Full FRED API v1 coverage: series, categories, releases, sources, and tags

• FastMCP 3.x with structured tool output and proper ToolError handling

• Dual-mode credentials: environment variable (stdio) or per-client HTTP header (remote BYOK)

• Transports: stdio, streamable-http, and sse

• Docker image published to GHCR

Installation

pip install fred-mcp

Requires Python 3.10+.

Get a free FRED API key at fredaccount.stlouisfed.org/apikey.

Setup

Remote hosted server (recommended)

Use the public hosted server with bring your own key (BYOK): no install and no shared server-side API key. Each client sends its own FRED API key in the X-FRED-API-Key header.

Transport: streamable HTTP. Endpoint: https://fred-mcp-prod.fly.dev/mcp.

Add this to your MCP client's configuration file and restart the client:

{
  "mcpServers": {
    "fred-mcp": {
      "url": "https://fred-mcp-prod.fly.dev/mcp",
      "headers": {
        "X-FRED-API-Key": "<your fred api key>"
      }
    }
  }
}

Programmatic example with the FastMCP client:

from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport

transport = StreamableHttpTransport(
    "https://fred-mcp-prod.fly.dev/mcp",
    headers={"X-FRED-API-Key": "your_fred_api_key"},
)
async with Client(transport=transport) as client:
    await client.ping()

Local (stdio)

For clients that spawn a local process, install fred-mcp and use:

{
  "mcpServers": {
    "fred-mcp": {
      "command": "fred-mcp",
      "env": {
        "FRED_API_KEY": "<your fred api key>"
      }
    }
  }
}

Or run directly from the terminal:

export FRED_API_KEY=your_api_key
fred-mcp

Self-hosted HTTP

Deploy your own instance and use the same url + headers configuration, substituting your host for the endpoint above. No shared server-side key is required when clients send X-FRED-API-Key.

For public internet deployment, terminate TLS at a reverse proxy (nginx, Caddy, Cloudflare). Do not expose plain HTTP with API keys.

Docker

Run the server:

docker run -d -p 8000:8000 \
  --name fred-mcp-server \
  ghcr.io/zachspar/fred-mcp/fred-mcp-server:latest

Connect with your FRED API key in the X-FRED-API-Key header (same JSON shape as the remote hosted example, with url set to your deployment).

For stdio via Docker:

{
  "mcpServers": {
    "fred-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_SERVER_TRANSPORT=stdio",
        "-e", "FRED_API_KEY=<your fred api key>",
        "ghcr.io/zachspar/fred-mcp/fred-mcp-server:latest"
      ]
    }
  }
}

Optional server-side fallback key

Set FRED_API_KEY on the server for clients that cannot send custom headers. Header takes precedence when both are present.

Tools (31)

Series

Categories

Releases

Sources

Tags

Migration from 0.x

Version 1.0.0 renames tools to snake_case and upgrades to FastMCP 3.x.

21 additional tools were added for categories, releases, sources, and tags.

Error responses now use MCP ToolError (isError: true) instead of {"error": ...} payloads.

Development

python3.13 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check src tests

License

MIT