Fred

fred-mcp

MCP server for Federal Reserve Economic Data. Wraps all 37 go-fred API endpoints as typed MCP tools. Connects over stdio (local) or HTTP/SSE (remote with OAuth).

Quick Start

1. Get a FRED API key

Register for free — takes 30 seconds.

2. Pick a mode

Stdio

Run locally via the installed binary, or with go run (no install):

# installed binary
FRED_API_KEY=your-key fred-mcp

# go run — no install needed
FRED_API_KEY=your-key go run github.com/shanehull/fred-mcp/cmd/fred-mcp@latest

Client config for most clients (Claude Code, Codex, Gemini CLI, Goose, VS Code):

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

Or without installing — point your client at go run:

{
  "mcpServers": {
    "fred": {
      "command": "go",
      "args": ["run", "github.com/shanehull/fred-mcp/cmd/fred-mcp@latest"],
      "env": { "FRED_API_KEY": "your-key" }
    }
  }
}

OpenCode uses its own format:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "fred": {
      "type": "local",
      "command": [
        "go",
        "run",
        "github.com/shanehull/fred-mcp/cmd/fred-mcp@latest",
      ],
      "enabled": true,
      "environment": {
        "FRED_API_KEY": "{env:FRED_API_KEY}",
      },
    },
  },
}

Where to put it: opencode.json (OpenCode), .codex.json (Codex), ~/.gemini/settings.json (Gemini CLI), .vscode/mcp.json (VS Code). Claude Code users can run /mcp add instead.

Serve

Run as an HTTP server (useful for remote access or Docker):

FRED_API_KEY=your-key fred-mcp serve

Or via Docker:

docker run -p 4000:4000 \
  -e FRED_API_KEY=your-key \
  ghcr.io/shanehull/fred-mcp:latest

Client config for SSE-capable clients (Cursor, etc.):

{
  "mcpServers": {
    "fred": {
      "url": "http://your-host:4000/sse"
    }
  }
}

Streamable HTTP clients can use http://your-host:4000/mcp.

3. Try it

Once connected, ask your agent: "What's the latest US unemployment rate?" — it will call get_series_observations with UNRATE.

API Key

Get a free key at fred.stlouisfed.org/docs/api/api_key.html. Pass it via the FRED_API_KEY environment variable — all modes respect it.

Serve Mode (HTTP/SSE)

Extended configuration reference for fred-mcp serve.

OAuth (optional)

When OAUTH_AUDIENCE is set, MCP routes require a valid Bearer token. The server acts as an OAuth proxy:

Tokens are validated via JWKS (JWT) with opaque token fallback (Google tokeninfo). Restrict access with OAUTH_ALLOWED_EMAILS (comma-separated). OAUTH_ALLOWED_EMAIL is deprecated but still works.

Point OAUTH_CALLBACK_URL at this server (for example https://fred.example.com/oauth/callback) and register the same URL as an authorized redirect URI on the Google OAuth client. The client must be a Web application; desktop app clients only allow loopback redirect URIs and cannot own a proxy callback. The callback flow requires OAUTH_AUDIENCE and OAUTH_CLIENT_SECRET. The proxy terminates the Google redirect and returns to the MCP client itself, so the response carries no RFC 9207 iss parameter.

Authorization codes are delivered only to loopback redirects (http://localhost, http://127.0.0.1, http://[::1]) unless the exact URI is listed in OAUTH_REDIRECT_URIS.

Docker

docker run -p 4000:4000 \
  -e FRED_API_KEY=your-key \
  ghcr.io/shanehull/fred-mcp:latest

The container runs serve mode. Add OAuth env vars to enable authentication. Multi-arch (linux/amd64, linux/arm64), FROM scratch (~8 MB).

Tool Reference

All 37 FRED API endpoints, one MCP tool each. Every tool returns JSON.

Series (12 tools)

Observation tools accept optional parameters: observation_start, observation_end, realtime_start, realtime_end, units, frequency, aggregation_method, output_type, vintage_dates, sort_order, limit, offset.

Categories (5 tools)

Releases (8 tools)

Sources (3 tools)

Tags (3 tools)

Search (3 tools)

Search tools accept optional parameters: search_type, order_by, sort_order, filter_variable, filter_value, limit, tag_names, exclude_tag_names.

GeoFRED (3 tools)

Configuration

All settings via environment variables.

Common

Serve mode

Install

# Go install
go install github.com/shanehull/fred-mcp/cmd/fred-mcp@latest

# Nix
nix profile install github:shanehull/fred-mcp

# Docker
docker pull ghcr.io/shanehull/fred-mcp:latest

# Prebuilt binary (from GitHub Releases)
curl -fsSL https://github.com/shanehull/fred-mcp/releases/latest/download/fred-mcp-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/') -o /usr/local/bin/fred-mcp
chmod +x /usr/local/bin/fred-mcp