Fred St Louis

БесплатноHosted

Enables users to query and explore economic data from FRED, supporting tools for searching series, retrieving observations, and browsing categories. It provides

автор: nicoloceneda

GitHub

Описание

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

Author: Nicolo Ceneda
Contact: [email protected]
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

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 Series ID specified.

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

Functionality and endpoint coverage

The server includes both dedicated tools and generic passthrough tools.

Generic passthrough

fred_request(endpoint, params_json) for /fred/*
geofred_request(endpoint, params_json) for /geofred/*
fred_v2_request(endpoint, params_json) for /fred/v2/*

FRED categories

get_category -> fred/category
get_category_children -> fred/category/children
get_category_related -> fred/category/related
get_category_series -> fred/category/series
get_category_tags -> fred/category/tags
get_category_related_tags -> fred/category/related_tags

FRED releases

get_releases -> fred/releases
get_releases_dates -> fred/releases/dates
get_release -> fred/release
get_release_dates -> fred/release/dates
get_release_series -> fred/release/series
get_release_sources -> fred/release/sources
get_release_tags -> fred/release/tags
get_release_related_tags -> fred/release/related_tags
get_release_tables -> fred/release/tables

FRED series

get_series -> fred/series
get_series_categories -> fred/series/categories
get_observations -> fred/series/observations
get_series_observations -> alias of get_observations
get_series_release -> fred/series/release
search_series -> fred/series/search
search_series_by_tags -> fred/series/search/tags
search_series_related_tags -> fred/series/search/related_tags
get_series_tags -> fred/series/tags
get_series_updates -> fred/series/updates
get_series_vintage_dates -> fred/series/vintagedates

FRED sources

get_sources -> fred/sources
get_source -> fred/source
get_source_releases -> fred/source/releases

FRED tags

get_tags -> fred/tags
get_related_tags -> fred/related_tags
get_tag_series -> fred/tags/series

GeoFRED maps

get_map_shape_file -> geofred/shapes/file
get_map_series_group -> geofred/series/group
get_map_series_data -> geofred/series/data
get_map_regional_data -> geofred/regional/data

FRED v2

get_release_observations_v2 -> fred/v2/release/observations

Как установить

Добавь это в claude_desktop_config.json и перезапусти Claude Desktop.

{
  "mcpServers": {
    "fred-st-louis-mcp": {
      "command": "npx",
      "args": []
    }
  }
}

Fred St Louis

Описание

README

Description

Requirements

Installation Step 1: Cloning and API Key

Installation Step 2: Configure MCP clients

Path A: Codex CLI

Path B: Claude Code CLI

Optional: Generic `mcpServers` JSON config

Optional quick smoke test

Examples

Functionality and endpoint coverage

Как установить

Похожие MCP

GitHub

Supabase

Everything

Filesystem

Command Palette

Fred St Louis

Описание

README

Description

Requirements

Installation Step 1: Cloning and API Key

Installation Step 2: Configure MCP clients

Path A: Codex CLI

Path B: Claude Code CLI

Optional: Generic mcpServers JSON config

Optional quick smoke test

Examples

Functionality and endpoint coverage

Как установить

Похожие MCP

GitHub

Supabase

Everything

Filesystem

Optional: Generic `mcpServers` JSON config