MCP 服务器

Fred St Louis MCP

Enables users to query and explore economic data from FRED, supporting tools for searching series, retrieving observations, and browsing categories. It provides comprehensive access to financial datasets, including GeoFRED maps and raw endpoint passthrough for advanced research.

README

Fred St Louis MCP

Project cover

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: fred with Status = 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

<details> <summary>Use this when your MCP client expects a JSON-based manual server configuration (for Claude Code team-shared setup, this is typically .mcp.json).</summary>

{
  "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"
      }
    }
  }
}

</details>

Optional quick smoke test

<details> <summary>Show optional smoke test script</summary>

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

</details>

Examples

<details> <summary>Calling MCP explicitly and with Series ID specified.</summary>

$ 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:

GS10 chart via MCP

Original graph by FRED:

GS10 chart

</details>

<details> <summary>Without calling MCP explicitly and no Series ID specified.</summary>

$ codex
OpenAI Codex (v0.101.0)
model: gpt-5.3-codex xhigh
directory: ~

> Tell me the latest value of US GDP (nominal).

I’ll pull the most recent GDP observation from FRED now and report its date and value.

Called fred.get_observations({"series_id":"GDP","limit":1,"sort_order":"desc"})

Latest FRED nominal U.S. GDP (GDP) is 31,098.027 (billions of dollars, SAAR), for 2025-07-01 (i.e., 2025 Q3).

</details>