ForexFactory MCP Server

Instructions

Implementation Reference

• src/forexfactory_mcp/tools/get_calendar_tool.py:24-74 (handler)

  The core handler function that implements the tool logic: parses input time_period or custom dates, scrapes events from ForexFactory using FFScraperService, normalizes them using extract_and_normalize_events, and returns a list of event dictionaries.

  async def get_calendar_events(
      time_period: Optional[str] = None,
      start_date: Optional[str] = None,
      end_date: Optional[str] = None,
  ) -> list[dict]:  # 👈 return JSON, not Pydantic
      """
      Parameters
      ----------
      time_period : str, optional
          Named period such as today, tomorrow, yesterday, this_week,
          next_week, last_week, this_month, next_month, last_month, custom.
      start_date : str, optional
          Start date in YYYY-MM-DD (required if time_period='custom').
      end_date : str, optional
          End date in YYYY-MM-DD (required if time_period='custom').
  
      Returns
      -------
      List[Event]
          List of structured calendar events.
      """
  
      # CASE 1: Named time period
      if time_period and time_period.lower() != "custom":
          try:
              # normalize before parsing
              normalized = time_period.strip().lower().replace(" ", "_")
              tp = TimePeriod.from_text(normalized)
          except ValueError:
              raise ValueError(
                  f"Invalid time_period '{time_period}'. "
                  f"Valid options: {', '.join([t.value for t in TimePeriod])}"
              )
  
          scraper = FFScraperService(time_period=tp)
          raw_events = await scraper.get_events()
  
      # CASE 2: Custom date range
      else:
          TimePeriod.validate_date_format(start_date)
          TimePeriod.validate_date_format(end_date)
          scraper = FFScraperService(
              time_period=TimePeriod.CUSTOM,
              custom_start_date=start_date,
              custom_end_date=end_date,
          )
          raw_events = await scraper.get_events()
  
      normalized = extract_and_normalize_events(raw_events)
  
      return normalized

• src/forexfactory_mcp/tools/get_calendar_tool.py:18-23 (registration)

  The @app.tool decorator that registers the tool with the exact name f'{namespace}_get_calendar_events' (namespace='ffcal'), along with description. Note: tool name becomes 'ffcal_get_calendar_events' by default.

  @app.tool(
      name=f"{namespace}_get_calendar_events",
      description="Retrieve ForexFactory calendar events for a given time period or custom date range."
      "Valid `time_period` values include: today, tomorrow, yesterday, "
      "this_week, next_week, last_week, this_month, next_month, last_month, custom.",
  )

• src/forexfactory_mcp/tools/tools_manager.py:17-17 (registration)

  Invocation of register_get_calendar_tool within the central tools_manager.register_tools function.

  register_get_calendar_tool(app, namespace)

• src/forexfactory_mcp/server.py:94-94 (registration)

  High-level registration call in server setup_app function, passing the namespace from settings.

  register_tools(_app, settings.NAMESPACE)

• src/forexfactory_mcp/settings.py:51-51 (helper)

  Defines the NAMESPACE='ffcal' used to prefix tool names, resulting in 'ffcal_get_calendar_events'. This could be overridden to 'my-ffcal' via environment variable.

  NAMESPACE: str = "ffcal"