ForexFactory MCP Server

Instructions

Implementation Reference

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

  The handler function that executes the tool logic: fetches raw events from ForexFactory using FFScraperService based on time_period or custom dates, normalizes them using event_utils, 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 name '{namespace}_get_calendar_events' (e.g., 'ffcal_get_calendar_events') and its description.
  @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:10-19 (registration)

  The register_tools function that calls register_get_calendar_tool to register the tool with the MCP app.
  def register_tools(app: FastMCP, namespace: str) -> None: """ Register all available MCP tools here. """ logger.info("Registering MCP tools...") # Add tools here register_get_calendar_tool(app, namespace) logger.info("All tools registered.")
• src/forexfactory_mcp/server.py:87-94 (registration)

  The setup_app function called during server initialization that invokes register_tools to register all tools including get_calendar_events.
  def setup_app(_app): """ Register all resources, prompts, and tools with the FastMCP app. This ensures that the server exposes the full MCP API surface. """ register_resources(_app, settings.NAMESPACE) register_prompts(_app, settings.NAMESPACE) register_tools(_app, settings.NAMESPACE)
• src/forexfactory_mcp/settings.py:51-51 (helper)

  Defines the namespace 'ffcal' which is used to construct the full tool name 'ffcal_get_calendar_events'.
  NAMESPACE: str = "ffcal"