# FRED MCP Server

A local [Model Context Protocol](https://modelcontextprotocol.io) server that gives Claude
and other MCP clients access to [Federal Reserve Economic Data (FRED)](https://fred.stlouisfed.org) —
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_id`s 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](https://docs.astral.sh/uv/)** — used to manage the environment and run the server
- **A free FRED API key** — get one at [fredaccount.stlouisfed.org/apikey](https://fredaccount.stlouisfed.org/apikey)

---

## Installation

```bash
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:

```bash
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):

```json
{
  "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

```bash
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.