Calendar Module — MCP Tool Specification

This document describes the 5 MCP tools exposed by codomyrmex.calendar_integration.mcp_tools.

All tools require:

• GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET environment variables
• ~/.codomyrmex/gcal_token.json (written by PAI dashboard OAuth flow)
• Google Calendar dependencies installed: uv sync --extra calendar

---

calendar_list_events

List upcoming events from Google Calendar.

Input Schema

Parameter	Type	Required	Description
days_ahead	int	No	Number of days to look ahead (default 7)

Output Schema

{
  "status": "ok",
  "events": [
    {
      "id": "abc123_20260224T100000Z",
      "summary": "Team Meeting",
      "start_time": "2026-02-24T10:00:00+00:00",
      "end_time": "2026-02-24T11:00:00+00:00",
      "description": "Weekly sync",
      "location": "Zoom",
      "attendees": ["colleague@example.com"],
      "html_link": "https://www.google.com/calendar/event?eid=..."
    }
  ]
}

On error: {"status": "error", "message": "<message>"}. The short-lived provider session is closed after the request, including when the API call fails.

---

calendar_create_event

Create a new event in Google Calendar.

Note: FristonBlanket@gmail.com is automatically added to attendees on every event, even when attendees=[] or attendees=None. Override via CODOMYRMEX_CALENDAR_ATTENDEE env var.

Input Schema

Parameter	Type	Required	Description
summary	str	Yes	Event title
start_time	str	Yes	ISO 8601 string, e.g. "2026-02-24T10:00:00Z"
end_time	str	Yes	ISO 8601 string, e.g. "2026-02-24T11:00:00Z"
description	str	No	Event description (default empty)
location	str	No	Location (default empty)
attendees	`List[str] \	None`	No Additional attendee email addresses

Output Schema

{
  "status": "ok",
  "event_id": "abc123_20260224T100000Z",
  "link": "https://www.google.com/calendar/event?eid=..."
}

On error: {"status": "error", "message": "<message>"}. The short-lived provider session is closed after the request, including when the API call fails.

---

calendar_get_event

Get details of a specific calendar event by its provider ID.

Input Schema

Parameter	Type	Required	Description
event_id	str	Yes	Google Calendar event ID

Output Schema

{
  "status": "ok",
  "event": {
    "id": "abc123_20260224T100000Z",
    "summary": "Team Meeting",
    "start_time": "2026-02-24T10:00:00+00:00",
    "end_time": "2026-02-24T11:00:00+00:00",
    "description": "Weekly sync",
    "location": "Zoom",
    "attendees": ["colleague@example.com"],
    "html_link": "https://www.google.com/calendar/event?eid=..."
  }
}

On error: {"status": "error", "message": "<message>"}. The short-lived provider session is closed after the request, including when the API call fails.

---

calendar_delete_event

Permanently delete a calendar event by ID.

Input Schema

Parameter	Type	Required	Description
event_id	str	Yes	Google Calendar event ID to delete

Output Schema

{
  "status": "ok",
  "deleted": true
}

On error: {"status": "error", "message": "<message>"}. The short-lived provider session is closed after the request, including when the API call fails.

---

calendar_update_event

Update an existing calendar event (PUT semantics — all fields replaced).

Note: FristonBlanket@gmail.com is automatically added to attendees on every update. Override via CODOMYRMEX_CALENDAR_ATTENDEE env var.

Input Schema

Parameter	Type	Required	Description
event_id	str	Yes	Google Calendar event ID to update
summary	str	Yes	Replacement event title
start_time	str	Yes	ISO 8601 string, e.g. "2026-02-24T10:00:00Z"
end_time	str	Yes	ISO 8601 string, e.g. "2026-02-24T11:00:00Z"
description	str	No	Replacement description (default empty)
location	str	No	Replacement location (default empty)
attendees	`List[str] \	None`	No Replacement attendee list

Output Schema

{
  "status": "ok",
  "event_id": "abc123_20260224T100000Z",
  "link": "https://www.google.com/calendar/event?eid=..."
}

On error: {"status": "error", "message": "<message>"}. The short-lived provider session is closed after the request, including when the API call fails.