Calendar Scheduling & Events

Relevant source files

The following files were used as context for generating this wiki page:

• packages/google-workspace-mcp/src/google_workspace_mcp/services/calendar.py
• packages/google-workspace-mcp/src/google_workspace_mcp/tools/calendar.py
• packages/google-workspace-mcp/src/google_workspace_mcp/prompts/calendar.py
• packages/google-workspace-mcp/src/google_workspace_mcp/resources/calendar.py
• tests/google-workspace-mcp/unit/tools/calendar/test_event_tools.py
• tests/google-workspace-mcp/integration/test_calendar_api.py

The Calendar Scheduling & Events system within the google-workspace-mcp package provides a standardized interface for interacting with Google Calendar through the Model Context Protocol (MCP). It enables AI assistants to perform comprehensive event management, including retrieving schedules, creating new meetings, and managing existing calendar entries.

This module is architected using a layered approach where the CalendarService handles direct API communication, while specialized MCP Tools, Resources, and Prompts expose these capabilities to AI models. The system supports multi-calendar access, timezone management, and attendee notifications.

Sources: packages/google-workspace-mcp/README.md:162-184, packages/google-workspace-mcp/src/google_workspace_mcp/services/calendar.py

System Architecture

The architecture follows the standard MCP server pattern implemented across the project. It separates the business logic of interacting with the Google Calendar API from the protocol-specific handling required for LLM interaction.

Service Layer: CalendarService

The CalendarService is the core class responsible for authenticating and executing requests against the Google Calendar API. It encapsulates the complexities of RFC3339 timestamp formatting, error handling, and response parsing.

Key Service Operations

Operation	Description	Target Endpoint/Logic
list_calendars	Retrieves all calendars the user has access to.	calendarList().list()
get_events	Fetches events within a specific time range.	events().list()
create_event	Schedules a new event with optional attendees.	events().insert()
delete_event	Removes an event by ID.	events().delete()
get_event_details	Retrieves full metadata for a specific event.	events().get()

Sources: packages/google-workspace-mcp/src/google_workspace_mcp/services/calendar.py, tests/google-workspace-mcp/integration/test_calendar_api.py:38-55

MCP Tools

Tools are the primary mechanism for AI models to take action. The calendar tools provide a high-level abstraction over the service layer, including validation for required fields like summary and start_time.

Event Management Flow

Tool Definitions

The system exposes the following core tools:

• calendar_get_events: Filters events using time_min and time_max parameters.
• create_calendar_event: Supports complex parameters including attendees (list of emails), location, description, and send_notifications.
• delete_calendar_event: Requires an event_id and allows specifying whether to notify attendees of the cancellation.

Sources: packages/google-workspace-mcp/README.md:162-184, packages/google-workspace-mcp/src/google_workspace_mcp/tools/calendar.py

MCP Resources

Resources provide the AI model with "read-only" context about the user's calendar state. These are identified by URIs and return structured data.

Available Resource URIs

URI	Description	Implementation Detail
calendar://calendars/list	Returns a list of all calendar objects and their metadata.	Calls service.list_calendars()
calendar://events/today	Automatically calculates the RFC3339 range for the current 24-hour period.	Uses pytz.UTC and timedelta

Sources: packages/google-workspace-mcp/src/google_workspace_mcp/resources/calendar.py:19-76

# Implementation of the today resource
@mcp.resource("calendar://events/today")
async def get_today_events() -> dict[str, Any]:
    now = datetime.now(pytz.UTC)
    start_of_day = datetime(now.year, now.month, now.day, 0, 0, 0, tzinfo=pytz.UTC)
    end_of_day = start_of_day + timedelta(days=1)
    # ... fetches events between start_of_day and end_of_day

Sources: packages/google-workspace-mcp/src/google_workspace_mcp/resources/calendar.py:53-70

Calendar Prompts

Prompts are predefined templates that guide the LLM on how to interact with calendar data. The draft_calendar_agenda prompt is used to help the model generate structured meeting agendas based on existing event details.

While currently implementing a simulation for unavailable details, the architectural intent is to use ctx.read_resource to pull live event data into the prompt context.

Sources: packages/google-workspace-mcp/src/google_workspace_mcp/prompts/calendar.py:18-40, tests/google-workspace-mcp/unit/prompts/test_calendar_prompts.py:16-36

Data Models

The system primarily interacts with the Google Calendar Event resource structure.

Field	Type	Description
id	string	Unique identifier for the event.
summary	string	The title of the event.
start.dateTime	string	Start time in RFC3339 format.
end.dateTime	string	End time in RFC3339 format.
attendees	list	List of objects containing email strings.
htmlLink	string	URL to the event in the Google Calendar web UI.

Sources: packages/google-workspace-mcp/src/google_workspace_mcp/services/calendar.py, tests/google-workspace-mcp/unit/tools/calendar/test_event_tools.py:127-135

Summary

The Calendar Scheduling & Events module provides a robust, test-driven implementation for managing Google Calendar via MCP. By abstracting the Google Calendar API into Tools and Resources, it allows AI models to efficiently navigate schedules and manage time-based commitments with precise control over timezones and attendee communications.