Federal Reserve Economic Data MCP Server

[!NOTE] This open-source project is not affiliated with, sponsored by, or endorsed by the Federal Reserve or the Federal Reserve Bank of St. Louis. "FRED" is a registered trademark of the Federal Reserve Bank of St. Louis, used here for descriptive purposes only.

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 4 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.list_tools()

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

The image is published only when a GitHub Release is published. That push tags latest, the release's git tag, and the released commit SHA.

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.

Each MCP tool call writes one JSON line to stderr. The line includes the tool name, the arguments, the result or error, and the duration. On HTTP it also includes the method, path, and mcp-session-id when that header is present. The FRED API key is not logged. Stderr is used so stdio transport keeps its protocol frames on stdout.

Tools (31)

Series

Categories

Releases

Sources

Tags

Development

python3.13 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
make check

License

MIT