How do I use FRED API MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@FRED API MCP Server show me the latest inflation rate (CPI)" 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 API MCP Server

by mike-whypred

Overview Schema Source Related Servers Discussions Admin

Python

Remote

MCP-FREDAPI

FRED (Federal Reserve Economic Data) API integration with Model Context Protocol (MCP)

Related MCP server: FRED Macroeconomic Data MCP Server

Introduction

MCP-FREDAPI provides access to economic data from the Federal Reserve Bank of St. Louis (FRED) through the Model Context Protocol. This integration allows AI assistants like Claude to retrieve economic time series data directly when used with Cursor or other MCP-compatible environments.

This package integrates with the official FRED API, focusing specifically on the series_observations endpoint which provides time series data for economic indicators.

Installation

There are two installation methods:

Method 1: Using pip

Install the required dependencies:

pip install "mcp[cli]" httpx python-dotenv

Clone this repository:

git clone https://github.com/mike-whypred/fred-api-mcp.git
cd fred-api-mcp

Method 2: Using uv (Recommended)

This method is recommended as it matches the configuration shown in mcp.json.

First, install uv if you don't have it yet:

pip install uv

Clone this repository:

git clone https://github.com/mike-whypred/fred-api-mcp.git
cd fred-api-mcp

Use uv to run the server (no need to install dependencies separately):

uv run --with mcp --with httpx mcp run server.py

Configuration

FRED API Key

You'll need a FRED API key, which you can obtain from FRED API.

Create a .env file in the project root:

FRED_API_KEY=your_api_key_here

Claude/Cursor Configuration

To configure Cursor to use this MCP server, add the following to your ~/.cursor/mcp.json file:

{
  "mcpServers": {
    "mcp-fredapi": {
      "command": "uv",
      "args": ["--directory", "/path/to/fred-api-mcp", "run", "--with", "mcp", "--with", "httpx", "mcp", "run", "server.py"]
    }
  }
}

Replace /path/to/mcp-fredapi with the actual path to the repository on your system. For example:

{
  "mcpServers": {
    "mcp-fredapi": {
      "command": "uv",
      "args": ["--directory", "/path/to/fred-api-mcp", "run", "--with", "mcp", "--with", "httpx", "mcp", "run", "server.py"]
    }
  }
}

Note: On Windows, you can use either forward slashes / or double backslashes \\ in the path.

Available Tools

get_fred_series_observations

Retrieves economic time series observations from FRED.

When using Claude in Cursor, you can access this tool directly with:

@mcp-fredapi:get_fred_series_observations

Parameters

The get_fred_series_observations tool accepts the following parameters. For complete technical details about each parameter, please refer to the official FRED API documentation.

Parameter	Type	Description	Allowed Values	Default Value	Status
series_id	str	The ID of the economic series	-	(Required)	✅ Works
sort_order	str	Sort order of observations	'asc', 'desc'	'asc'	✅ Works
units	str	Data value transformation	'lin', 'chg', 'ch1', 'pch', 'pc1', 'pca', 'cch', 'cca', 'log'	'lin'	✅ Works
frequency	str	Frequency of observations	'd', 'w', 'bw', 'm', 'q', 'sa', 'a', 'wef', 'weth', 'wew', 'wetu', 'wem', 'wesu', 'wesa', 'bwew', 'bwem'	None	✅ Works
aggregation_method	str	Aggregation method for frequency	'avg', 'sum', 'eop'	'avg'	✅ Works
output_type	int	Output type of observations	1, 2, 3, 4	1	✅ Works
realtime_start	str	Start of real-time period (YYYY-MM-DD)	-	None	❌ Not working
realtime_end	str	End of real-time period (YYYY-MM-DD)	-	None	❌ Not working
limit	int/str	Maximum number of observations to return	Between 1 and 100000	10	❌ Not working
offset	int/str	Number of observations to skip from the beginning	-	0	❌ Not working
observation_start	str	Start date of observations (YYYY-MM-DD)	-	None	❌ Not working
observation_end	str	End date of observations (YYYY-MM-DD)	-	None	❌ Not working
vintage_dates	str	Comma-separated list of vintage dates	-	None	❌ Not working

WARNING

Due to current limitations with the MCP implementation, only certain parameters are working properly:

✅ Working parameters: series_id, sort_order, units, frequency , aggregation_method, and output_type`.
❌ Non-working parameters: realtime_start, realtime_end, limit, offset, observation_start, observation_end, and vintage_dates.

For best results, stick with the working parameters in your queries. Future updates may resolve these limitations.

Examples

Getting US GDP Data

When using Claude in Cursor, you can ask for GDP data like this:

Can you get the latest GDP data from FRED?

@mcp-fredapi:get_fred_series_observations
{
  "series_id": "GDP"
}

Getting GDP Data in Descending Order

Can you get the GDP data in descending order (newest first)?

@mcp-fredapi:get_fred_series_observations
{
  "series_id": "GDP",
  "sort_order": "desc"
}

Getting Annual GDP Data

Can you get annual GDP data?

@mcp-fredapi:get_fred_series_observations
{
  "series_id": "GDP",
  "frequency": "a"
}

Getting Inflation Rate

To get consumer price index data with percent change:

What's the recent inflation rate in the US?

@mcp-fredapi:get_fred_series_observations
{
  "series_id": "CPIAUCSL",
  "units": "pch",
  "frequency": "m"
}

Different Output Format

Show me GDP data in a different format.

@mcp-fredapi:get_fred_series_observations
{
  "series_id": "GDP",
  "output_type": 2
}

Contributing

Contributions are welcome. Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Commit your changes (git commit -m 'Add an amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

References

FRED API Documentation - Series Observations - Official documentation for the FRED API endpoint used in this project.
FRED API - Information on obtaining an API key and general API documentation.
Model Context Protocol - Documentation for the Model Context Protocol.

Available Tools

1 tool

get_fred_series_observationsC

Get series observations from the Fred API.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum number of observations to return. Defaults to 10.
`units`	No	Data value transformation. Options: 'lin', 'chg', 'ch1', 'pch', 'pc1', 'pca', 'cch', 'cca', 'log'. Defaults to 'lin'.	lin
`offset`	No	Number of observations to offset from first. Defaults to 0.
`frequency`	No	Frequency of observations. Options: 'd', 'w', 'bw', 'm', 'q', 'sa', 'a', 'wef', 'weth', 'wew', 'wetu', 'wem', 'wesu', 'wesa', 'bwew', 'bwem'. Defaults to no value for no frequency aggregation.
`series_id`	Yes	The id for a series.
`sort_order`	No	Sort order of observations. Options: 'asc' or 'desc'. Defaults to 'asc'.	asc
`output_type`	No	Output type of observations. Options: 1, 2, 3, 4. Defaults to 1.
`realtime_end`	No	The end of the real-time period. Format: YYYY-MM-DD. Defaults to today's date.
`vintage_dates`	No	Comma-separated list of vintage dates.
`realtime_start`	No	The start of the real-time period. Format: YYYY-MM-DD. Defaults to today's date.
`observation_end`	No	End date of observations. Format: YYYY-MM-DD.
`observation_start`	No	Start date of observations. Format: YYYY-MM-DD.
`aggregation_method`	No	Aggregation method for frequency. Options: 'avg', 'sum', 'eop'. Defaults to 'avg'.	avg

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Get', implying a read operation, but does not describe response format, pagination behavior, real-time period semantics, potential errors, or any side effects. The description is too thin to inform the agent about how the tool behaves beyond the obvious.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with zero wasted words and is front-loaded with the core verb and resource. It is appropriately brief, though given the tool's complexity, a little more structure could have made it more useful without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a 13-parameter tool with no output schema and no annotations. The description does not explain what an 'observation' is, what the return payload looks like, or how concepts like vintage dates and real-time periods work. The schema covers parameters, but the overall tool context is under-specified for an agent to use it confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 100% description coverage across all 13 parameters, so the baseline is 3. The description itself contributes nothing to parameter understanding, but the schema adequately documents defaults, formats, and enums, so no deduction beyond baseline is warranted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb ('Get') and resource ('series observations') with the API ('Fred'), which adequately identifies the operation. However, it does not elaborate on what 'observations' actually are or provide any differentiating detail, and it closely mirrors the tool name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given about when to use this tool, what conditions favor it, or what alternatives exist. Since there are no sibling tools, there is no differentiation burden, but there is also no scenario or prerequisite context to help an agent decide to invoke it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

1 tool updatev0.1.0Aug 30, 2026
- First observedget_fred_series_observations

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3/5.0

Scored 2026-08-30 12:05 across 1 tool

Disambiguation5/5

Only one tool exists, so there is no possibility of ambiguity or misselection. The tool's purpose is clearly defined and distinct by default.

Naming Consistency5/5

The single tool name follows a clear snake_case verb_noun convention. With only one tool, the naming is trivially consistent.

Tool Count2/5

One tool is too few for a server claiming to represent the FRED API, which has a broad range of endpoints. The apparent scope far exceeds what a single tool can cover.

Completeness1/5

The FRED API supports many resource types (series, categories, releases, sources, etc.) beyond just fetching observations. This server only exposes one observation endpoint, leaving the surface severely incomplete for the stated purpose.

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

timeslope-mcpOAuth
com.timeslope
Equip AI with tools for researching economic data from Federal Reserve Economic Data (FRED).
Government Data Finance Open Data
2
LastLook Data A
io.github.zev-lll
FRED macro data, Treasury yields, FX rates & macro indicators for AI agents. Pay-per-query via x402.
Finance Research & Data
242
Slacking.biz — SEC Financial Data + US Economics + Demographics + FX C
io.github.Th3Slack3r
75 MCP tools: SEC financials, FRED economics, IRS 990, FDA, FX, UK Companies House.
Finance Government Data Open Data
751
bls-labor-mcp-server A
io.github.cyanheads
Fetch US Bureau of Labor Statistics data — CPI, unemployment, wages, JOLTS, and more via MCP.
Government Data Open Data
621

Related MCP Servers

MCP-FREDAPI
Government Data Open Data Search
Jaldekoa
A
license
C
quality
D
maintenance
Provides access to economic data from the Federal Reserve Bank of St. Louis (FRED) through the Model Context Protocol, allowing AI assistants to retrieve economic time series data directly.
Updated a year ago (2025-04-09 11:21 UTC)
1
6
MIT
FRED Macroeconomic Data MCP
Finance Government Data Search
hungson175
F
license
Not graded
quality
D
maintenance
Provides 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.
Updated a year ago (2025-04-06 02:48 UTC)
8
-
mcp-fred
Government Data Finance Open Data
PetrefiedThunder
F
license
Not graded
quality
D
maintenance
An MCP server that wraps the Federal Reserve Economic Data (FRED) API, providing access to over 800,000 economic time series like GDP and unemployment. It enables AI agents to search for data, retrieve metadata, and fetch historical observations directly from the St. Louis Fed.
Updated 3 months ago (2026-06-01 19:10 UTC)
-
FRED API MCP Server
Finance Government Data Open Data
dracepj
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.
Updated a year ago (2025-06-29 08:05 UTC)
7
1
-

MCP-FREDAPI

Table of Contents

Introduction

Installation

Method 1: Using pip

Method 2: Using uv (Recommended)

Configuration

FRED API Key

Claude/Cursor Configuration

Available Tools

get_fred_series_observations

Parameters

Examples

Getting US GDP Data

Getting GDP Data in Descending Order

Getting Annual GDP Data

Getting Inflation Rate

Different Output Format

Contributing

License

References

Available Tools

TDQS

Tool Schema Changelog

TDQS

Resources

Related MCP Connectors

Related MCP Servers

MCP-FREDAPI

FRED Macroeconomic Data MCP

mcp-fred

FRED API MCP Server