# cre-fred-mcp

An MCP server that pulls **live Federal Reserve economic data** (FRED) — the
rates a CRE capital-markets routine runs on: SOFR, Treasury yields, the Fed
funds rate, mortgage rates, CPI and PCE. Instead of re-scraping by hand, your
MCP client pulls the current numbers on every run.

## Quickstart — let Claude set it up for you

Not technical? You don't need to be. **Hand this repo to Claude and let it do the work:**

1. Open **Claude Desktop** (or Claude Code).
2. Give it this repo — paste the URL `https://github.com/nik-mirando/cre-fred-mcp`
   (or this README) and say: *"Help me install this MCP server in my Claude Desktop, step by step."*
3. Claude walks you through the three things it needs:
   - a **free FRED API key** (~2 minutes, instant, no credit card — see below),
   - installing the server,
   - adding it to your Claude config and restarting.

Once it's connected, just ask the questions further down and Claude pulls the live numbers itself.

> The one step Claude can't do for you is **create the free FRED account** — it'll
> hand you the link and tell you exactly where to paste the key. Everything else it handles.

## Example questions to ask once it's connected

- *"Give me a CRE capital markets snapshot."*
- *"What's SOFR today, and the 10-year Treasury?"*
- *"What's the current 30-year mortgage rate, and how has it moved this year?"*
- *"What's CPI and PCE inflation right now, year over year?"*
- *"Pull the Fed funds rate and the 2s/10s Treasury spread."*

## Tools

| Tool | What it returns |
|------|-----------------|
| `get_capital_markets_snapshot` | One call: SOFR, UST 2/5/10/30yr, Fed funds, 30yr mortgage (latest %), plus CPI & PCE year-over-year % |
| `get_latest_value(series_id)` | Most recent **non-missing** observation for any series |
| `get_series_observations(series_id, ...)` | Time series with date/value (supports `units` like `pc1` = YoY %, and `frequency` aggregation) |
| `get_series_metadata(series_id)` | Title, units, frequency, last updated |
| `search_series(query)` | Find series by free-text |
| `list_common_series` | Curated CRE-relevant series ids |

Missing values (FRED's `"."`, common on daily series over holidays) are
normalised to `null`, never crash, and are skipped by `get_latest_value`.

## Get a free API key

FRED keys are free and issued instantly:

1. Create / sign in to a FRED account.
2. Go to <https://fredaccount.stlouisfed.org/apikeys> and request a key.
3. Copy the 32-character key.

## Install

```bash
# from source (this folder)
pip install .
# or run without installing, via uv
uvx --from . cre-fred-mcp
```

Set the key (either export it or drop a `.env` next to the server):

```bash
cp .env.example .env   # then paste your key
```

## MCP client config

```jsonc
{
  "mcpServers": {
    "cre-fred": {
      "command": "uvx",
      "args": ["--from", "/abs/path/to/cre-fred-mcp", "cre-fred-mcp"],
      "env": { "FRED_API_KEY": "your_key_here" }
    }
  }
}
```

(Or `"command": "python", "args": ["-m", "cre_fred_mcp"]` with the package installed.)

## Verify it works (live)

```bash
python smoke_test.py
```

Makes real calls and asserts on real values — e.g. that `DGS10` metadata titles
the 10-Year Treasury and that the latest `SOFR` print is a sane numeric rate.

## Data source

Data: [FRED](https://fred.stlouisfed.org/), Federal Reserve Bank of St. Louis.
This is an unofficial client and is not affiliated with or endorsed by the Fed.
Series are subject to FRED's terms of use.