my-ffcal_get_calendar_events

Retrieve ForexFactory economic calendar events for specific time periods or custom date ranges to support trading analysis and workflow integration.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`time_period`	No
`start_date`	No
`end_date`	No

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"
```

ForexFactory MCP Server