fred-macro-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@fred-macro-mcp what is the current unemployment rate?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
GETrequests against the single fixed hosthttps://api.stlouisfed.org. There is no write, mutation, or order-placement path of any kind.
Tools
Tool | Purpose |
| Observation values for one series over an optional date window. |
| Keyword-search the FRED catalog to find the right |
| The single most-recent observation for a series. |
| Upcoming FRED data releases in the next N days. |
| Local health probe (key configured? rate limit?). Never calls FRED. |
| 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), optionalstart/end(YYYY-MM-DD), optionallimit.Output:
{ series_id, start, end, units, observation_count, observations: [{date, value}, ...] }. Missing points ("."in FRED) surface asvalue: 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), optionallimit.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 |
|
Real GDP |
|
CPI (all urban) |
|
Core PCE |
|
Unemployment rate |
|
Fed funds (effective) |
|
10-year Treasury |
|
2-year Treasury |
|
10y-2y spread |
|
Install
uv sync --extra devA 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 |
| (required) | 32-char FRED key. Never logged. |
|
| Client throttle (≤ FRED's 120/min ceiling). |
|
| Opt-in read-through cache. |
|
| Force fresh reads while still writing. |
|
|
|
| (unset) | DSN used only when backend is |
|
| 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_idand 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 srcTests 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 toolsget_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
Scored across 6 tools
Each tool has a clearly distinct purpose: release calendar, series data retrieval (full or latest), search, and server info/health. No overlapping functionality.
All tools use consistent snake_case with a verb_noun pattern (get_*, search_*, health_check). The pattern is predictable and easy to understand.
6 tools is well-scoped for a FRED macro data server. It covers essential operations without being too many or too few.
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
Related MCP Connectors
Equip AI with tools for researching economic data from Federal Reserve Economic Data (FRED).
FRED macro data, Treasury yields, FX rates & macro indicators for AI agents. Pay-per-query via x402.
Macro data for AI agents: GDP, inflation, unemployment and more (World Bank, US BLS). No keys.
Macro data for AI agents: GDP, inflation, unemployment and more (World Bank, US BLS). No keys.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides 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-
- AlicenseNot gradedqualityDmaintenanceProvides 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
- AlicenseAqualityCmaintenanceEnables 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.938 PyPIMIT
- AlicenseAqualityDmaintenanceEnables users to search, retrieve, and explore economic data series from the Federal Reserve Economic Data (FRED) API using natural language.11MIT