fred-macro-mcp

A read-only Model Context Protocol (MCP) server that wraps the FRED (Federal Reserve Economic Data, St. Louis Fed) public API.

FRED is the canonical free source for US macroeconomic time series — GDP, CPI, unemployment, policy and market interest rates, and the Treasury yield curve. This server lets an LLM agent overlay macro context on equity / fixed-income research: "what is CPI doing", "where is the 10y-2y spread", "when is the next jobs print".

Read-only by design. Every tool performs HTTPS GET requests against the single fixed host https://api.stlouisfed.org. There is no write, mutation, or order-placement path of any kind.

Tools

get_series

• When to use: pull a macro time series (e.g. CPI, GDP, 10y Treasury).
• Input: series_id (e.g. CPIAUCSL), optional start / end

(YYYY-MM-DD), optional limit.

• Output: `{ series_id, start, end, units, observation_count,

observations: [{date, value}, ...] }. Missing points ("." in FRED) surface as value: null`.

• Example: get_series(series_id="DGS10", start="2024-01-01").

search_series

• When to use: you know the concept ("unemployment rate") but not the id.
• Input: query (free text), optional limit.
• Output: `{ query, result_count, results: [{id, title, frequency,

units, observation_start, observation_end, popularity}, ...] }`, most popular first.

• Example: search_series(query="real gdp").

get_series_latest

• When to use: "what is the current value of X" without the full history.
• Input: series_id.
• Output: { series_id, latest: {date, value} | null, units }.
• Example: get_series_latest(series_id="UNRATE").

get_release_calendar

• When to use: flag upcoming macro event risk (next CPI / GDP / jobs).
• Input: days (1-180, default 14).
• Output: `{ days, from_date, to_date, release_count, releases:

[{release_id, release_name, date}, ...] }`.

• Example: get_release_calendar(days=30).

Common series ids

Install

uv sync --extra dev

A FRED API key (free) is required. Copy .env.example to .env and set FRED_API_KEY.

Configure your MCP host

Add to your MCP host config (e.g. Cursor ~/.cursor/mcp.json):

{
  "mcpServers": {
    "fred-macro": {
      "command": "uv",
      "args": ["run", "fred-macro-mcp"],
      "cwd": "/opt/workspace/code/kevinkda/fred-macro-mcp",
      "env": { "FRED_API_KEY": "<your-fred-key>" }
    }
  }
}

FRED_API_KEY may also be set in .env instead of inline env.

Configuration

The cache is off by default and uses an in-process memory LRU when enabled — zero external dependencies. ClickHouse is an opt-in extra (pip install fred-macro-mcp[clickhouse]) for durable history.

Security

• API key is the only secret. It is read from the environment, passed

to FRED only as a bound query parameter, and redacted from every log line and exception message (api_key=… and bare 32-char keys are masked).

• SSRF-safe. The host is a hard-coded constant; callers supply an

endpoint path + params only and can never redirect to another host. Redirects are not followed.

• Injection-safe. series_id and dates are validated with anchored

regexes and passed as bound query parameters — never string-concatenated into a URL.

• Rate-limited. A sliding-60-second token bucket keeps requests within

FRED's documented 120 req/min budget.

See docs/SECURITY.md and docs/THREAT_MODEL.md.

Development

uv run pytest --cov=src --cov-fail-under=100
uv run ruff check src tests && uv run ruff format --check src tests
uv run mypy --strict src

Tests use respx to mock FRED — no real FRED API calls are made in the test suite.

License

MIT — see LICENSE.

Data © Federal Reserve Bank of St. Louis (FRED). Subject to FRED's terms of use. This server is for interactive single-user research.