Skip to main content
Glama
fred-macro-mcp

fred-macro-mcp

by kevinkda

fred-macro-mcp

CI CodeQL License: MIT

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

Tool

Purpose

get_series

Observation values for one series over an optional date window.

search_series

Keyword-search the FRED catalog to find the right series_id.

get_series_latest

The single most-recent observation for a series.

get_release_calendar

Upcoming FRED data releases in the next N days.

health_check

Local health probe (key configured? rate limit?). Never calls FRED.

get_server_info

Version, MCP SDK version, tool list. Never calls FRED.

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).

Related MCP server: FRED Economic MCP Server

Common series ids

Concept

series_id

Real GDP

GDPC1

CPI (all urban)

CPIAUCSL

Core PCE

PCEPILFE

Unemployment rate

UNRATE

Fed funds (effective)

DFF

10-year Treasury

DGS10

2-year Treasury

DGS2

10y-2y spread

T10Y2Y

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

Env var

Default

Purpose

FRED_API_KEY

(required)

32-char FRED key. Never logged.

FRED_RATE_LIMIT_PER_MIN

120

Client throttle (≤ FRED's 120/min ceiling).

FRED_CACHE_ENABLED

false

Opt-in read-through cache.

FRED_CACHE_BYPASS

false

Force fresh reads while still writing.

FRED_CACHE_BACKEND

memory

memory (zero-dep) or clickhouse (opt-in extra).

FRED_CLICKHOUSE_URL

(unset)

DSN used only when backend is clickhouse.

LOG_LEVEL

WARNING

Log verbosity.

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.

Available Tools

6 tools
get_release_calendarA

Return upcoming FRED data releases in the next days days.

Useful for macro overlay: knowing when the next CPI / GDP / jobs print lands lets an agent flag event risk on the calendar.

Inputs: days. Returns: object

get_seriesB

Return the observation series for a FRED economic data series.

series_id is a FRED identifier (e.g. GDP, CPIAUCSL, UNRATE, DGS10). start / end optionally bound the window as ISO YYYY-MM-DD dates.

Inputs: series_id (required), end, limit, start. Returns: object

get_series_latestA

Return the single most-recent observation for a FRED series.

Cheaper than get_series when an agent only needs the current value of a macro indicator.

Inputs: series_id (required). Returns: object

get_server_infoA

Local server metadata. Never calls FRED.

Inputs: no named parameters. Returns: object

health_checkA

Local health probe. Never calls FRED.

Inputs: no named parameters. Returns: object

search_seriesA

Search the FRED catalog for series matching query keywords.

Returns the most popular matches with their frequency, units, and observation range so an agent can pick the right series_id.

Inputs: query (required), limit. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: release calendar, series data retrieval (full or latest), search, and server info/health. No overlapping functionality.

    Naming Consistency5/5

    All tools use consistent snake_case with a verb_noun pattern (get_*, search_*, health_check). The pattern is predictable and easy to understand.

    Tool Count5/5

    6 tools is well-scoped for a FRED macro data server. It covers essential operations without being too many or too few.

    Completeness4/5

    Covers search, retrieval (full and latest), release calendar, and server metadata. Minor gap: no bulk data retrieval for multiple series in one call, but the core workflow is complete.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides access to Federal Reserve Economic Data (FRED) through Claude and other LLM clients, enabling users to search for, retrieve, and visualize economic indicators like GDP, employment, and inflation data.
      8
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides access to 800,000+ Federal Reserve Economic Data (FRED) time series, enabling users to search, retrieve, and analyze economic indicators like GDP, unemployment, inflation, and interest rates through natural language queries.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to search and retrieve FRED economic time series, including vintage (as-published) data, with tools for series search, observation retrieval, release calendar, revision history, and more.
      9
      38 PyPI
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables users to search, retrieve, and explore economic data series from the Federal Reserve Economic Data (FRED) API using natural language.
      11
      MIT