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