A1 AI engineering company GitHub
Connect the Google Calendar MCP server to your AI agent Open source, MIT, on npm. Setup instructions for Claude, Cursor and Codex are in the repository; adoption questions — Telegram. GitHub repository Telegram

Google Calendar: List events — MCP tool

Google Calendar MCP tool: Lists events on a calendar within a time window, with search, sorting and recurring-event expansion.

Technical name: list_events

What task it solves

I want to see what is on a calendar for a given period.

Returns the events on one calendar: id, summary, start/end, status, attendees with their response status, organizer, recurrence, Meet link and event type.

When to use it

Use it for "what's on my calendar" questions — with single_events: true so recurring events appear as concrete occurrences (also required for order_by: start_time). Use q to search by text, and updated_min + show_deleted for incremental polling of changes.

What to provide

  • calendar_id — required. From list_calendars, or "primary".
  • time_min / time_max — optional. RFC3339 window bounds (events overlapping the window are included).
  • q — optional. Free-text search over summary, description, location and attendees.
  • single_events — optional. Expand recurring events into instances.
  • order_by — optional. start_time (needs single_events: true) or updated.
  • time_zone — optional. IANA zone the response times are rendered in.
  • max_results, page_token — optional. Pagination (1..2500 per page).
  • show_deleted, updated_min — optional. Incremental polling of changes.
  • event_types — optional. Filter, e.g. ["out_of_office"].

What it returns

Compact JSON with items[] and nextPageToken when more pages exist. All-day events carry date with an EXCLUSIVE end date; timed events carry dateTime.

What changes in Google Calendar

The tool reads Google Calendar data and does not change it.

Example request

What meetings do I have next week, in my local time zone?

Errors and limitations

time_zone only changes how times are rendered, never the events themselves. Without single_events, a recurring series appears once as its master. A too-old updated_min returns HTTP 410 — restart with a plain window. Cancelled events come back only with show_deleted: true.

Access also depends on token permissions, quotas, and upstream API limits.

Related MCP tools

Technical details