list_events
Retrieve calendar events from Google Calendar by specifying date ranges, calendars, and sorting options to view scheduled activities.
Instructions
List events from a Google Calendar
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| calendarId | No | Calendar ID (default: 'primary') | primary |
| timeMin | No | Lower bound for event start time (RFC3339 timestamp) | |
| timeMax | No | Upper bound for event start time (RFC3339 timestamp) | |
| maxResults | No | Maximum number of events to return (default: 250) | |
| singleEvents | No | Whether to expand recurring events (default: true) | |
| orderBy | No | Order of events (default: 'startTime') | startTime |
Implementation Reference
- src/index.ts:338-376 (handler)Handler function that executes the list_events tool: validates args, calls Google Calendar API events.list, returns formatted events or error.
async function handleListEvents(args: z.infer<typeof ListEventsArgsSchema>) { try { const response = await calendar.events.list({ calendarId: args.calendarId, timeMin: args.timeMin, timeMax: args.timeMax, maxResults: args.maxResults, singleEvents: args.singleEvents, orderBy: args.orderBy, }); return { content: [ { type: "text", text: JSON.stringify({ success: true, events: response.data.items || [], nextPageToken: response.data.nextPageToken, summary: `Found ${(response.data.items || []).length} events`, }, null, 2), }, ], }; } catch (error) { return { content: [ { type: "text", text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : "Unknown error", }, null, 2), }, ], isError: true, }; } } - src/index.ts:38-45 (schema)Zod schema defining input parameters for the list_events tool, used for validation in the handler dispatcher.
const ListEventsArgsSchema = z.object({ calendarId: z.string().optional().default("primary"), timeMin: z.string().optional(), timeMax: z.string().optional(), maxResults: z.number().optional().default(250), singleEvents: z.boolean().optional().default(true), orderBy: z.enum(["startTime", "updated"]).optional().default("startTime"), }); - src/index.ts:113-150 (registration)Tool object registration in the tools array, defining name, description, and input schema for MCP ListTools response.
{ name: "list_events", description: "List events from a Google Calendar", inputSchema: { type: "object", properties: { calendarId: { type: "string", description: "Calendar ID (default: 'primary')", default: "primary", }, timeMin: { type: "string", description: "Lower bound for event start time (RFC3339 timestamp)", }, timeMax: { type: "string", description: "Upper bound for event start time (RFC3339 timestamp)", }, maxResults: { type: "number", description: "Maximum number of events to return (default: 250)", default: 250, }, singleEvents: { type: "boolean", description: "Whether to expand recurring events (default: true)", default: true, }, orderBy: { type: "string", enum: ["startTime", "updated"], description: "Order of events (default: 'startTime')", default: "startTime", }, }, }, }, - src/index.ts:547-549 (registration)Dispatch case in CallToolRequestHandler that validates args with schema and calls the list_events handler.
case "list_events": { const validatedArgs = ListEventsArgsSchema.parse(args); return await handleListEvents(validatedArgs);