FRED MCP Server

A local Model Context Protocol server that gives Claude and other MCP clients access to Federal Reserve Economic Data (FRED) — 800,000+ economic time series covering GDP, inflation, employment, interest rates, and more.

---

Tools

Tool	Description
search_series	Find a series by natural-language query (e.g. "unemployment rate"), returns the most relevant series_ids ordered by popularity.
get_series_info	Metadata for a series — title, units, frequency, date range, and notes.
get_observations	The actual time-series values, with optional transforms (e.g. year-over-year %) and frequency aggregation.

---

Prerequisites

• Python 3.10+
• uv — used to manage the environment and run the server
• A free FRED API key — get one at fredaccount.stlouisfed.org/apikey

---

Installation

git clone https://github.com/yifudiao/fred-mcp.git
cd fred-mcp
uv sync

---

Use with Claude Desktop

Quick install (recommended)

From the project directory:

uv run mcp install server.py --name "FRED" -v FRED_API_KEY=your_key

This writes the connector into Claude Desktop's config for you. Fully quit and reopen Claude Desktop (closing the window is not enough) and the FRED tools will appear.

Manual config

Alternatively, edit claude_desktop_config.json directly (Claude Desktop → Settings → Developer → Edit Config):

{
  "mcpServers": {
    "fred": {
      "command": "uv",
      "args": ["--directory", "/ABSOLUTE/PATH/TO/fred-mcp", "run", "server.py"],
      "env": { "FRED_API_KEY": "your_key" }
    }
  }
}

The --directory flag is what makes uv use this project (and its installed dependencies) regardless of where Claude Desktop launches the process from.

---

Use with Claude Code

claude mcp add fred -s user -e FRED_API_KEY=your_key -- \
  uv --directory /ABSOLUTE/PATH/TO/fred-mcp run server.py

• -s user makes the server available across all your projects (drop it to scope it to the current project).
• Verify with claude mcp list, or /mcp inside a session.

For a project-scoped, committable setup, add a .mcp.json to your project root with the same command instead.

---

Try it out

Example prompts:

• Using fred, what is the current unemployment rate?
• Using fred, look at the recession indicators, summarize them in a table and assign a probability of recession in 2026.

---

Notes & troubleshooting

• Editing the server: changes to server.py are picked up on the next Claude Desktop restart — no reinstall needed. Don't move or rename the project folder, though; the config points at its absolute path.
• Never print() to stdout in a tool. stdout is the JSON-RPC channel for stdio transport; use the MCP Context logging methods or write to stderr.
• Result-size limit: Claude caps tool results at ~150k characters, so get_observations limits the number of points returned. For long daily series, use frequency to aggregate rather than raising the limit.
• uv: command not found: GUI apps on macOS don't inherit your shell's PATH, so a freshly installed uv in ~/.local/bin may not be found. Fix by using the absolute path to uv (which uv) as the command in your config.
• Logs: on macOS, see ~/Library/Logs/Claude/mcp-server-*.log for the spawned server's stdout/stderr — the fastest way to diagnose a failed launch.