Query and explore economic data from FRED
Fred St Louis MCP
Author: Nicolo Ceneda
Contact: n.ceneda20@imperial.ac.uk
Website: nicoloceneda.github.io
Institution: Imperial College London
Course: PhD in Finance
Description
This repository provides an MCP server that lets MCP-compatible clients query and explore economic data from FRED. It exposes structured tools for common workflows (searching series, retrieving observations, browsing categories/releases/tags) and also supports raw endpoint passthrough for advanced use cases.
Supported APIs:
- FRED API v1 (
/fred/*) - GeoFRED maps API (
/geofred/*) - FRED API v2 (
/fred/v2/*)
Requirements
- Python
>=3.11 - A FRED API key from FRED API Keys
Installation Step 1: Cloning and API Key
First, cd into the directory where you want the mcp-fred repository to be created. Then execute the following commands from the terminal.
git clone https://github.com/nicoloceneda/mcp-fred.git
cd mcp-fred
python3 -m venv .venv
.venv/bin/pip install -e .
Create a local .env:
cp .env.example .env
Then set:
FRED_API_KEY=your_fred_api_key_here
Installation Step 2: Configure MCP clients
Path A: Codex CLI
Run once (note: you need to replace /absolute/path/to/ with your actual path):
codex mcp add fred -- /absolute/path/to/mcp-fred/.venv/bin/python /absolute/path/to/mcp-fred/fred_server.py
Check:
codex mcp list
codex mcp get fred
Successful setup should show:
- In
codex mcp list:fredwithStatus=enabled - In
codex mcp get fred:enabled: true
Launch Codex (codex) and verify that the MCP has successfully been installed (/mcp).
Path B: Claude Code CLI
Run once (note: you need to replace /absolute/path/to/ with your actual path):
claude mcp add --transport stdio fred -- /absolute/path/to/mcp-fred/.venv/bin/python /absolute/path/to/mcp-fred/fred_server.py
Check:
claude mcp list
claude mcp get fred
Launch Claude Code (claude) and verify that the MCP has successfully been installed (/mcp).
Optional: Generic `mcpServers` JSON config
Use this when your MCP client expects a JSON-based manual server configuration (for Claude Code team-shared setup, this is typically `.mcp.json`).
{
"mcpServers": {
"fred": {
"command": "/absolute/path/to/mcp-fred/.venv/bin/python",
"args": ["/absolute/path/to/mcp-fred/fred_server.py"],
"env": {
"FRED_API_KEY": "your_fred_api_key_here"
}
}
}
}
Optional quick smoke test
Show optional smoke test script
Run this script to verify that the MCP server starts, the stdio MCP connection initializes correctly, and a real tool call (search_series) succeeds.
cd mcp-fred
.venv/bin/python - <<'PY'
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async def main():
params = StdioServerParameters(
command=".venv/bin/python",
args=["fred_server.py"],
)
async with stdio_client(params) as (r, w):
async with ClientSession(r, w) as s:
await s.initialize()
tools = await s.list_tools()
print("tool_count =", len(tools.tools))
out = await s.call_tool("search_series", {"query": "unemployment rate", "limit": 1})
print(out.content[0].text)
asyncio.run(main())
PY
Examples
Calling MCP explicitly and with Series ID specified.
$ codex
OpenAI Codex (v0.101.0)
model: gpt-5.3-codex xhigh
directory: ~
> Use the FRED MCP to retrieve the last 13 values of GS10 and create a matplotlib line chart saved to /Users/nicoloceneda/Desktop/gs10.png.
I’ll fetch the latest 13 GS10 observations via FRED MCP, then generate and save a matplotlib line chart at /Users/nicoloceneda/Desktop/gs10.png.
Called fred.get_observations({"series_id":"GS10","sort_order":"desc","limit":13})
Retrieved the last 13 GS10 observations from FRED and created the matplotlib line chart.
Saved file: /Users/nicoloceneda/Desktop/gs10.png
Values used (most recent first):
- 2026-01-01: 4.21
- 2025-12-01: 4.14
- 2025-11-01: 4.09
- 2025-10-01: 4.06
- 2025-09-01: 4.12
- 2025-08-01: 4.26
- 2025-07-01: 4.39
- 2025-06-01: 4.38
- 2025-05-01: 4.42
- 2025-04-01: 4.28
- 2025-03-01: 4.28
- 2025-02-01: 4.45
- 2025-01-01: 4.63
Graph generated by MCP:
Original graph by FRED:
Without calling MCP explicitly and no
Tools (2)
search_seriesSearch for economic data seriesget_observationsRetrieve observations for a specific seriesEnvironment Variables
FRED_API_KEYrequiredAPI key obtained from FRED API KeysConfiguration
{"mcpServers": {"fred": {"command": "/absolute/path/to/mcp-fred/.venv/bin/python", "args": ["/absolute/path/to/mcp-fred/fred_server.py"], "env": {"FRED_API_KEY": "your_fred_api_key_here"}}}}