MCP-FREDAPI

Instructions

Implementation Reference

• server.py:30-93 (handler)

  The @mcp.tool decorated async function implementing the get_fred_series_observations tool. Handles input parameters, constructs API params, calls the make_request helper to fetch data from FRED API endpoint /series/observations, and returns the observations list.
  @mcp.tool(name="get_fred_series_observations", description="""Get series observations from the Fred API.""") async def get_fred_series_observations( series_id: Annotated[str, Field(description="The id for a series.")], realtime_start: Annotated[Optional[str], Field(description="The start of the real-time period. Format: YYYY-MM-DD. Defaults to today's date.")] = None, realtime_end: Annotated[Optional[str], Field(description="The end of the real-time period. Format: YYYY-MM-DD. Defaults to today's date.")] = None, limit: Annotated[Optional[int | str], Field(description="Maximum number of observations to return. Defaults to 10.")] = 10, offset: Annotated[Optional[int | str], Field(description="Number of observations to offset from first. Defaults to 0.")] = 0, sort_order: Annotated[Literal['asc', 'desc'], Field(description="Sort order of observations. Options: 'asc' or 'desc'. Defaults to 'asc'.")] = 'asc', observation_start: Annotated[Optional[str], Field(description="Start date of observations. Format: YYYY-MM-DD.")] = None, observation_end: Annotated[Optional[str], Field(description="End date of observations. Format: YYYY-MM-DD.")] = None, 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', 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, aggregation_method: Annotated[Literal['avg', 'sum', 'eop'], Field(description="Aggregation method for frequency. Options: 'avg', 'sum', 'eop'. Defaults to 'avg'.")] = 'avg', output_type: Annotated[Literal[1, 2, 3, 4], Field(description="Output type of observations. Options: 1, 2, 3, 4. Defaults to 1.")] = 1, vintage_dates: Annotated[Optional[str], Field(description="Comma-separated list of vintage dates.")] = None, ): """Get series observations from the Fred API. Args: series_id (str): The id for a series. realtime_start (str): The start of the real-time period. YYYY-MM-DD formatted string, optional, default: today's date. realtime_end (str): The end of the real-time period. YYYY-MM-DD formatted string, optional, default: today's date. limit (int or str): The maximum number of observations to return. Optional, default: 1000. offset (int or str): The number of observations to offset from the first observation. Optional, default: 0. sort_order (str): The sort order of the observations. Possible values: "asc" or "desc". Optional, default: "asc". observation_start (str): The start date of the observations to get. YYYY-MM-DD formatted string. Optional, default: 1776-07-04 (earliest available). observation_end (str): The end date of the observations to get. YYYY-MM-DD formatted string. Optional, default: 9999-12-31 (latest available). 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). 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. 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". output_type (int): The output type of the observations. Optional, default: 1. vintage_dates (str): A comma-separated list of vintage dates to return. Optional, default: no vintage dates are set by default. Returns: dict[str, str]: A dictionary containing the observations or data values for an economic data series. """ params = { "series_id": series_id, # ✅ "realtime_start": realtime_start, # ❌ "realtime_end": realtime_end, # ❌ "limit": limit, # ✅ "offset": offset, # ✅ "sort_order": sort_order, # ✅ "observation_start": observation_start, # ❌ "observation_end": observation_end, # ❌ "units": units, # ✅ "frequency": frequency, # ✅ "aggregation_method": aggregation_method, # ✅ "output_type": output_type, # ✅ "vintage_dates": vintage_dates, # ❌ "file_type": "json" } data = await make_request(f"{FRED_API_URL}/series/observations", params) if not data: raise ConnectionError("Failed to fetch data from the FRED API") observations = data["observations"] if not observations: raise ValueError("No observations found for the given series") return observations
• server.py:31-45 (schema)

  Input schema defined in the function parameters using Annotated with Pydantic Field for validation, descriptions, and types (e.g., series_id: str, limit: Optional[int|str], etc.).
  async def get_fred_series_observations( series_id: Annotated[str, Field(description="The id for a series.")], realtime_start: Annotated[Optional[str], Field(description="The start of the real-time period. Format: YYYY-MM-DD. Defaults to today's date.")] = None, realtime_end: Annotated[Optional[str], Field(description="The end of the real-time period. Format: YYYY-MM-DD. Defaults to today's date.")] = None, limit: Annotated[Optional[int | str], Field(description="Maximum number of observations to return. Defaults to 10.")] = 10, offset: Annotated[Optional[int | str], Field(description="Number of observations to offset from first. Defaults to 0.")] = 0, sort_order: Annotated[Literal['asc', 'desc'], Field(description="Sort order of observations. Options: 'asc' or 'desc'. Defaults to 'asc'.")] = 'asc', observation_start: Annotated[Optional[str], Field(description="Start date of observations. Format: YYYY-MM-DD.")] = None, observation_end: Annotated[Optional[str], Field(description="End date of observations. Format: YYYY-MM-DD.")] = None, 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', 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, aggregation_method: Annotated[Literal['avg', 'sum', 'eop'], Field(description="Aggregation method for frequency. Options: 'avg', 'sum', 'eop'. Defaults to 'avg'.")] = 'avg', output_type: Annotated[Literal[1, 2, 3, 4], Field(description="Output type of observations. Options: 1, 2, 3, 4. Defaults to 1.")] = 1, vintage_dates: Annotated[Optional[str], Field(description="Comma-separated list of vintage dates.")] = None, ):
• server.py:30-30 (registration)

  Tool registration decorator @mcp.tool(name="get_fred_series_observations", description=...).
  @mcp.tool(name="get_fred_series_observations", description="""Get series observations from the Fred API.""")
• server.py:15-29 (helper)

  make_request helper function that performs authenticated async HTTP GET requests to FRED API using httpx, adding API key from env.
  async def make_request(url: str, params: dict): """Make a request to the Federal Reserve Economic Data API.""" if FRED_API_KEY := os.getenv("FRED_API_KEY"): params["api_key"] = FRED_API_KEY async with httpx.AsyncClient() as client: try: response = await client.get(url, params=params) response.raise_for_status() return response.json() except httpx.HTTPStatusError as e: raise ConnectionError(f"Failed to fetch data from the FRED API: {e}")