# Directory Structure
```
├── .gitignore
├── .python-version
├── LICENSE
├── pyproject.toml
├── README.md
├── server.py
└── uv.lock
```
# Files
--------------------------------------------------------------------------------
/.python-version:
--------------------------------------------------------------------------------
```
1 | 3.13
2 |
```
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 | # Python-generated files
2 | __pycache__/
3 | *.py[oc]
4 | build/
5 | dist/
6 | wheels/
7 | *.egg-info
8 |
9 | # Virtual environments
10 | .venv
11 |
12 | # Environment variables
13 | .env
14 |
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP-FREDAPI
2 |
3 | **FRED (Federal Reserve Economic Data) API integration with Model Context Protocol (MCP)**
4 |
5 | ## Table of Contents
6 |
7 | - [Introduction](#introduction)
8 | - [Installation](#installation)
9 | - [Configuration](#configuration)
10 | - [FRED API Key](#fred-api-key)
11 | - [Claude/Cursor Configuration](#claudecursor-configuration)
12 | - [Available Tools](#available-tools)
13 | - [Parameters](#parameters)
14 | - [Examples](#examples)
15 | - [Common Economic Series IDs](#common-economic-series-ids)
16 | - [Contributing](#contributing)
17 | - [License](#license)
18 | - [References](#references)
19 |
20 | ## Introduction
21 |
22 | 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.
23 |
24 | This package integrates with the [official FRED API](https://fred.stlouisfed.org/docs/api/fred/), focusing specifically on the [series_observations endpoint](https://fred.stlouisfed.org/docs/api/fred/series_observations.html) which provides time series data for economic indicators.
25 |
26 | ## Installation
27 |
28 | There are two installation methods:
29 |
30 | ### Method 1: Using pip
31 |
32 | Install the required dependencies:
33 |
34 | ```terminal
35 | pip install "mcp[cli]" httpx python-dotenv
36 | ```
37 |
38 | Clone this repository:
39 |
40 | ```terminal
41 | git clone https://github.com/Jaldekoa/mcp-fredapi.git
42 | cd mcp-fredapi
43 | ```
44 |
45 | ### Method 2: Using uv (Recommended)
46 |
47 | This method is recommended as it matches the configuration shown in mcp.json.
48 |
49 | 1. First, install uv if you don't have it yet:
50 |
51 | ```terminal
52 | pip install uv
53 | ```
54 |
55 | 2. Clone this repository:
56 |
57 | ```terminal
58 | git clone https://github.com/Jaldekoa/mcp-fredapi.git
59 | cd mcp-fredapi
60 | ```
61 |
62 | 3. Use uv to run the server (no need to install dependencies separately):
63 |
64 | ```terminal
65 | uv run --with mcp --with httpx mcp run server.py
66 | ```
67 |
68 | ## Configuration
69 |
70 | ### FRED API Key
71 |
72 | You'll need a FRED API key, which you can obtain from [FRED API](https://fred.stlouisfed.org/docs/api/api_key.html).
73 |
74 | Create a `.env` file in the project root:
75 |
76 | ```
77 | FRED_API_KEY=your_api_key_here
78 | ```
79 |
80 | ### Claude/Cursor Configuration
81 |
82 | To configure Cursor to use this MCP server, add the following to your `~/.cursor/mcp.json` file:
83 |
84 | ```json
85 | {
86 | "mcpServers": {
87 | "mcp-fredapi": {
88 | "command": "uv",
89 | "args": ["--directory", "/path/to/mcp-fredapi", "run", "--with", "mcp", "--with", "httpx", "mcp", "run", "server.py"]
90 | }
91 | }
92 | }
93 | ```
94 |
95 | Replace `/path/to/mcp-fredapi` with the actual path to the repository on your system. For example:
96 |
97 | ```json
98 | {
99 | "mcpServers": {
100 | "mcp-fredapi": {
101 | "command": "uv",
102 | "args": ["--directory", "/path/to/mcp-fredapi", "run", "--with", "mcp", "--with", "httpx", "mcp", "run", "server.py"]
103 | }
104 | }
105 | }
106 | ```
107 |
108 | Note: On Windows, you can use either forward slashes `/` or double backslashes `\\` in the path.
109 |
110 | ## Available Tools
111 |
112 | ### get_fred_series_observations
113 |
114 | Retrieves economic time series observations from FRED.
115 |
116 | When using Claude in Cursor, you can access this tool directly with:
117 |
118 | ```
119 | @mcp-fredapi:get_fred_series_observations
120 | ```
121 |
122 | ## Parameters
123 |
124 | 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](https://fred.stlouisfed.org/docs/api/fred/series_observations.html).
125 |
126 | | Parameter | Type | Description | Allowed Values | Default Value | Status |
127 | |-----------|------|-------------|---------------|---------------|--------|
128 | | series_id | str | The ID of the economic series | - | (Required) | ✅ Works |
129 | | sort_order | str | Sort order of observations | 'asc', 'desc' | 'asc' | ✅ Works |
130 | | units | str | Data value transformation | 'lin', 'chg', 'ch1', 'pch', 'pc1', 'pca', 'cch', 'cca', 'log' | 'lin' | ✅ Works |
131 | | frequency | str | Frequency of observations | 'd', 'w', 'bw', 'm', 'q', 'sa', 'a', 'wef', 'weth', 'wew', 'wetu', 'wem', 'wesu', 'wesa', 'bwew', 'bwem' | None | ✅ Works |
132 | | aggregation_method | str | Aggregation method for frequency | 'avg', 'sum', 'eop' | 'avg' | ✅ Works |
133 | | output_type | int | Output type of observations | 1, 2, 3, 4 | 1 | ✅ Works |
134 | | realtime_start | str | Start of real-time period (YYYY-MM-DD) | - | None | ❌ Not working |
135 | | realtime_end | str | End of real-time period (YYYY-MM-DD) | - | None | ❌ Not working |
136 | | limit | int/str | Maximum number of observations to return | Between 1 and 100000 | 10 | ❌ Not working |
137 | | offset | int/str | Number of observations to skip from the beginning | - | 0 | ❌ Not working |
138 | | observation_start | str | Start date of observations (YYYY-MM-DD) | - | None | ❌ Not working |
139 | | observation_end | str | End date of observations (YYYY-MM-DD) | - | None | ❌ Not working |
140 | | vintage_dates | str | Comma-separated list of vintage dates | - | None | ❌ Not working |
141 |
142 | > [!WARNING]
143 | >
144 | > Due to current limitations with the MCP implementation, only certain parameters are working properly:
145 | > - ✅ **Working parameters**: `series_id`, `sort_order`, `units`, `frequency` , aggregation_method`, and `output_type`.
146 | > - ❌ **Non-working parameters**: `realtime_start`, `realtime_end`, `limit`, `offset`, `observation_start`, `observation_end`, and `vintage_dates`.
147 | >
148 | > For best results, stick with the working parameters in your queries. Future updates may resolve these limitations.
149 |
150 | ## Examples
151 |
152 | ### Getting US GDP Data
153 |
154 | When using Claude in Cursor, you can ask for GDP data like this:
155 |
156 | ```
157 | Can you get the latest GDP data from FRED?
158 |
159 | @mcp-fredapi:get_fred_series_observations
160 | {
161 | "series_id": "GDP"
162 | }
163 | ```
164 |
165 | ### Getting GDP Data in Descending Order
166 |
167 | ```
168 | Can you get the GDP data in descending order (newest first)?
169 |
170 | @mcp-fredapi:get_fred_series_observations
171 | {
172 | "series_id": "GDP",
173 | "sort_order": "desc"
174 | }
175 | ```
176 |
177 | ### Getting Annual GDP Data
178 |
179 | ```
180 | Can you get annual GDP data?
181 |
182 | @mcp-fredapi:get_fred_series_observations
183 | {
184 | "series_id": "GDP",
185 | "frequency": "a"
186 | }
187 | ```
188 |
189 | ### Getting Inflation Rate
190 |
191 | To get consumer price index data with percent change:
192 |
193 | ```
194 | What's the recent inflation rate in the US?
195 |
196 | @mcp-fredapi:get_fred_series_observations
197 | {
198 | "series_id": "CPIAUCSL",
199 | "units": "pch",
200 | "frequency": "m"
201 | }
202 | ```
203 |
204 | ### Different Output Format
205 |
206 | ```
207 | Show me GDP data in a different format.
208 |
209 | @mcp-fredapi:get_fred_series_observations
210 | {
211 | "series_id": "GDP",
212 | "output_type": 2
213 | }
214 | ```
215 |
216 | ## Contributing
217 |
218 | Contributions are welcome. Please follow these steps:
219 |
220 | 1. Fork the repository
221 | 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
222 | 3. Make your changes
223 | 4. Commit your changes (`git commit -m 'Add an amazing feature'`)
224 | 5. Push to the branch (`git push origin feature/amazing-feature`)
225 | 6. Open a Pull Request
226 |
227 | ## License
228 |
229 | This project is licensed under the MIT License - see the LICENSE file for details.
230 |
231 | ## References
232 |
233 | - [FRED API Documentation - Series Observations](https://fred.stlouisfed.org/docs/api/fred/series_observations.html) - Official documentation for the FRED API endpoint used in this project.
234 | - [FRED API](https://fred.stlouisfed.org/docs/api/api_key.html) - Information on obtaining an API key and general API documentation.
235 | - [Model Context Protocol](https://modelcontextprotocol.github.io/) - Documentation for the Model Context Protocol.
236 |
```
--------------------------------------------------------------------------------
/pyproject.toml:
--------------------------------------------------------------------------------
```toml
1 | [project]
2 | name = "mcp-fredapi"
3 | version = "0.1.0"
4 | description = "Add your description here"
5 | readme = "README.md"
6 | requires-python = ">=3.13"
7 | dependencies = [
8 | "httpx>=0.28.1",
9 | "mcp[cli]>=1.6.0",
10 | "python-dotenv>=1.1.0",
11 | ]
12 |
```
--------------------------------------------------------------------------------
/server.py:
--------------------------------------------------------------------------------
```python
1 | from mcp.server.fastmcp import FastMCP
2 | from typing import Annotated, Optional , Literal
3 | from dotenv import load_dotenv
4 | from pydantic import Field
5 | import httpx
6 | import os
7 |
8 | load_dotenv()
9 |
10 | mcp = FastMCP("mcp-fredapi", dependencies=["httpx", "python-dotenv"])
11 |
12 | FRED_API_URL = "https://api.stlouisfed.org/fred"
13 |
14 |
15 | async def make_request(url: str, params: dict):
16 | """Make a request to the Federal Reserve Economic Data API."""
17 |
18 | if FRED_API_KEY := os.getenv("FRED_API_KEY"):
19 | params["api_key"] = FRED_API_KEY
20 |
21 | async with httpx.AsyncClient() as client:
22 | try:
23 | response = await client.get(url, params=params)
24 | response.raise_for_status()
25 | return response.json()
26 |
27 | except httpx.HTTPStatusError as e:
28 | raise ConnectionError(f"Failed to fetch data from the FRED API: {e}")
29 |
30 | @mcp.tool(name="get_fred_series_observations", description="""Get series observations from the Fred API.""")
31 | async def get_fred_series_observations(
32 | series_id: Annotated[str, Field(description="The id for a series.")],
33 | realtime_start: Annotated[Optional[str], Field(description="The start of the real-time period. Format: YYYY-MM-DD. Defaults to today's date.")] = None,
34 | realtime_end: Annotated[Optional[str], Field(description="The end of the real-time period. Format: YYYY-MM-DD. Defaults to today's date.")] = None,
35 | limit: Annotated[Optional[int | str], Field(description="Maximum number of observations to return. Defaults to 10.")] = 10,
36 | offset: Annotated[Optional[int | str], Field(description="Number of observations to offset from first. Defaults to 0.")] = 0,
37 | sort_order: Annotated[Literal['asc', 'desc'], Field(description="Sort order of observations. Options: 'asc' or 'desc'. Defaults to 'asc'.")] = 'asc',
38 | observation_start: Annotated[Optional[str], Field(description="Start date of observations. Format: YYYY-MM-DD.")] = None,
39 | observation_end: Annotated[Optional[str], Field(description="End date of observations. Format: YYYY-MM-DD.")] = None,
40 | units: Annotated[Literal['lin', 'chg', 'ch1', 'pch', 'pc1', 'pca', 'cch', 'cca', 'log'], Field(description="Data value transformation. Options: 'lin', 'chg', 'ch1', 'pch', 'pc1', 'pca', 'cch', 'cca', 'log'. Defaults to 'lin'.")] = 'lin',
41 | frequency: Annotated[Literal['d', 'w', 'bw', 'm', 'q', 'sa', 'a', 'wef', 'weth', 'wew', 'wetu', 'wem', 'wesu', 'wesa', 'bwew', 'bwem'], Field(description="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.")] = None,
42 | aggregation_method: Annotated[Literal['avg', 'sum', 'eop'], Field(description="Aggregation method for frequency. Options: 'avg', 'sum', 'eop'. Defaults to 'avg'.")] = 'avg',
43 | output_type: Annotated[Literal[1, 2, 3, 4], Field(description="Output type of observations. Options: 1, 2, 3, 4. Defaults to 1.")] = 1,
44 | vintage_dates: Annotated[Optional[str], Field(description="Comma-separated list of vintage dates.")] = None,
45 | ):
46 | """Get series observations from the Fred API.
47 |
48 | Args:
49 | series_id (str): The id for a series.
50 | realtime_start (str): The start of the real-time period. YYYY-MM-DD formatted string, optional, default: today's date.
51 | realtime_end (str): The end of the real-time period. YYYY-MM-DD formatted string, optional, default: today's date.
52 | limit (int or str): The maximum number of observations to return. Optional, default: 1000.
53 | offset (int or str): The number of observations to offset from the first observation. Optional, default: 0.
54 | sort_order (str): The sort order of the observations. Possible values: "asc" or "desc". Optional, default: "asc".
55 | observation_start (str): The start date of the observations to get. YYYY-MM-DD formatted string. Optional, default: 1776-07-04 (earliest available).
56 | observation_end (str): The end date of the observations to get. YYYY-MM-DD formatted string. Optional, default: 9999-12-31 (latest available).
57 | units (str): A key that indicates a data value transformation. Posible values: 'lin', 'chg', 'ch1', 'pch', 'pc1', 'pca', 'cch', 'cca', 'log'. Optional, default: 'lin' (No transformation).
58 | frequency (str): The frequency of the observations. Posible values: 'd', 'w', 'bw', 'm', 'q', 'sa', 'a', 'wef', 'weth', 'wew', 'wetu', 'wem', 'wesu', 'wesa', 'bwew', 'bwem'. Optional, default: no value for no frequency aggregation.
59 | aggregation_method (str): A key that indicates the aggregation method used for frequency aggregation. This parameter has no affect if the frequency parameter is not set. Posible values: 'avg', 'sum', 'eop'. Optional, default: "avg".
60 | output_type (int): The output type of the observations. Optional, default: 1.
61 | vintage_dates (str): A comma-separated list of vintage dates to return. Optional, default: no vintage dates are set by default.
62 |
63 | Returns:
64 | dict[str, str]: A dictionary containing the observations or data values for an economic data series.
65 | """
66 | params = {
67 | "series_id": series_id, # ✅
68 | "realtime_start": realtime_start, # ❌
69 | "realtime_end": realtime_end, # ❌
70 | "limit": limit, # ✅
71 | "offset": offset, # ✅
72 | "sort_order": sort_order, # ✅
73 | "observation_start": observation_start, # ❌
74 | "observation_end": observation_end, # ❌
75 | "units": units, # ✅
76 | "frequency": frequency, # ✅
77 | "aggregation_method": aggregation_method, # ✅
78 | "output_type": output_type, # ✅
79 | "vintage_dates": vintage_dates, # ❌
80 | "file_type": "json"
81 | }
82 |
83 | data = await make_request(f"{FRED_API_URL}/series/observations", params)
84 |
85 | if not data:
86 | raise ConnectionError("Failed to fetch data from the FRED API")
87 |
88 | observations = data["observations"]
89 |
90 | if not observations:
91 | raise ValueError("No observations found for the given series")
92 |
93 | return observations
94 |
95 |
96 | if __name__ == "__main__":
97 | mcp.run()
98 |
```