Skip to main content
Glama
Fred St Louis MCP

Fred St Louis MCP

by nicoloceneda

Fred St Louis MCP

Project cover

Status: Active Development and Maintained

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/*)

Related MCP server: fred-mcp

Requirements

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

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

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

$ 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

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

  • fred_request(endpoint, params_json) for /fred/*

  • geofred_request(endpoint, params_json) for /geofred/*

  • fred_v2_request(endpoint, params_json) for /fred/v2/*

  • 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

  • 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

  • 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

  • get_sources -> fred/sources

  • get_source -> fred/source

  • get_source_releases -> fred/source/releases

  • get_tags -> fred/tags

  • get_related_tags -> fred/related_tags

  • get_tag_series -> fred/tags/series

  • 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

  • get_release_observations_v2 -> fred/v2/release/observations

Available Tools

40 tools
fred_requestC

Call any FRED API v1 endpoint path directly.

Inputs: endpoint (required), params_json. Returns: object

fred_v2_requestB

Call any FRED API v2 endpoint path directly.

Inputs: endpoint (required), params_json. Returns: object

geofred_requestC

Call any GeoFRED API endpoint path directly.

Inputs: endpoint (required), params_json. Returns: object

get_categoryD

fred/category

Inputs: category_id, realtime_start, realtime_end. Returns: object

get_category_childrenD

fred/category/children

Inputs: category_id, realtime_start, realtime_end. Returns: object

get_category_seriesD

fred/category/series

Inputs: category_id (required), limit, offset, order_by, +7 more. Returns: object

get_category_tagsD

fred/category/tags

Inputs: category_id (required), limit, offset, order_by, +6 more. Returns: object

get_map_regional_dataD

geofred/regional/data

Inputs: series_group (required), region_type (required), date (required), start_date, +5 more. Returns: object

get_map_series_dataD

geofred/series/data

Inputs: series_id (required), date, start_date. Returns: object

get_map_series_groupD

geofred/series/group

Inputs: series_id (required). Returns: object

get_map_shape_fileD

geofred/shapes/file

Inputs: shape (required). Returns: object

get_observationsD

fred/series/observations

Inputs: series_id (required), realtime_start, realtime_end, limit, +9 more. Returns: object

get_releaseD

fred/release

Inputs: release_id (required), realtime_start, realtime_end. Returns: object

get_release_datesD

fred/release/dates

Inputs: release_id (required), limit, offset, sort_order, +3 more. Returns: object

get_release_observations_v2D

fred/v2/release/observations

Inputs: release_id (required), date, series_id, limit, +3 more. Returns: object

get_releasesD

fred/releases

Inputs: limit, offset, order_by, sort_order, +2 more. Returns: object

get_releases_datesD

fred/releases/dates

Inputs: limit, offset, sort_order, include_release_dates_with_no_data, +2 more. Returns: object

get_release_seriesD

fred/release/series

Inputs: release_id (required), limit, offset, order_by, +7 more. Returns: object

get_release_sourcesD

fred/release/sources

Inputs: release_id (required), realtime_start, realtime_end. Returns: object

get_release_tablesD

fred/release/tables

Inputs: release_id (required), element_id, observation_date, include_observation_values. Returns: object

get_release_tagsD

fred/release/tags

Inputs: release_id (required), limit, offset, order_by, +6 more. Returns: object

get_seriesD

fred/series

Inputs: series_id (required), realtime_start, realtime_end. Returns: object

get_series_categoriesD

fred/series/categories

Inputs: series_id (required), realtime_start, realtime_end. Returns: object

get_series_observationsD

Alias for get_observations.

Inputs: series_id (required), realtime_start, realtime_end, limit, +9 more. Returns: object

get_series_releaseD

fred/series/release

Inputs: series_id (required), realtime_start, realtime_end. Returns: object

get_series_tagsD

fred/series/tags

Inputs: series_id (required), limit, offset, order_by, +6 more. Returns: object

get_series_updatesD

fred/series/updates

Inputs: realtime_start, realtime_end, limit, offset, +3 more. Returns: object

get_series_vintage_datesD

fred/series/vintagedates

Inputs: series_id (required), realtime_start, realtime_end, limit, +2 more. Returns: object

get_sourceD

fred/source

Inputs: source_id (required), realtime_start, realtime_end. Returns: object

get_source_releasesD

fred/source/releases

Inputs: source_id (required), realtime_start, realtime_end, limit, +3 more. Returns: object

get_sourcesD

fred/sources

Inputs: realtime_start, realtime_end, limit, offset, +2 more. Returns: object

get_tagsD

fred/tags

Inputs: realtime_start, realtime_end, limit, offset, +5 more. Returns: object

get_tag_seriesD

fred/tags/series

Inputs: tag_names (required), exclude_tag_names, realtime_start, realtime_end, +4 more. Returns: object

search_seriesD

fred/series/search

Inputs: query (required), search_type, limit, offset, +8 more. Returns: object

search_series_by_tagsD

fred/series/search/tags

Inputs: series_search_text (required), tag_names, limit, offset, +6 more. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2.1/5.0

    Scored across 40 tools

    Disambiguation4/5

    Most tools have distinct purposes targeting specific FRED resources and operations, but there is some overlap between general request tools (fred_request, fred_v2_request, geofred_request) and specific endpoint tools, which could cause confusion about when to use which. The alias 'get_series_observations' duplicates 'get_observations', adding minor redundancy.

    Naming Consistency5/5

    Tool names follow a highly consistent verb_noun pattern (e.g., get_category, search_series, get_release_dates) with clear snake_case throughout. The three general request tools (fred_request, fred_v2_request, geofred_request) deviate slightly but maintain a predictable naming style.

    Tool Count2/5

    With 40 tools, the count is excessive for the FRED API domain, making the surface overwhelming and likely to confuse agents. A more focused set of 10-20 tools covering core operations would be more appropriate, as many tools are highly specific (e.g., get_category_related_tags, get_release_tables) that could be consolidated.

    Completeness5/5

    The tool set provides comprehensive coverage of the FRED API domain, including categories, series, releases, sources, tags, and geospatial data, with full CRUD-like operations (mostly GET/search) and no apparent gaps. It supports all major workflows for economic data retrieval and analysis.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • 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
    • F
      license
      A
      quality
      D
      maintenance
      Enables searching and retrieving economic data from the Federal Reserve Economic Data (FRED) API, including time series, categories, releases, and popular indicators.
      7
      1
      -
    • 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