list_events
Retrieve and organize Google Calendar events by specifying filters like time range, event count, and order, enabling efficient event management and scheduling.
Instructions
List events from a Google Calendar
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| calendarId | No | Calendar ID (default: 'primary') | primary |
| maxResults | No | Maximum number of events to return (default: 250) | |
| orderBy | No | Order of events (default: 'startTime') | startTime |
| singleEvents | No | Whether to expand recurring events (default: true) | |
| timeMax | No | Upper bound for event start time (RFC3339 timestamp) | |
| timeMin | No | Lower bound for event start time (RFC3339 timestamp) |
Input Schema (JSON Schema)
{
"properties": {
"calendarId": {
"default": "primary",
"description": "Calendar ID (default: 'primary')",
"type": "string"
},
"maxResults": {
"default": 250,
"description": "Maximum number of events to return (default: 250)",
"type": "number"
},
"orderBy": {
"default": "startTime",
"description": "Order of events (default: 'startTime')",
"enum": [
"startTime",
"updated"
],
"type": "string"
},
"singleEvents": {
"default": true,
"description": "Whether to expand recurring events (default: true)",
"type": "boolean"
},
"timeMax": {
"description": "Upper bound for event start time (RFC3339 timestamp)",
"type": "string"
},
"timeMin": {
"description": "Lower bound for event start time (RFC3339 timestamp)",
"type": "string"
}
},
"type": "object"
}
Implementation Reference
- src/index.ts:338-376 (handler)The main handler function for the 'list_events' tool. It calls the Google Calendar API to list events based on provided parameters and returns the results or error in MCP content format.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 the input parameters and validation for the 'list_events' tool.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 registration in the 'tools' array, including name, description, and input schema for MCP ListToolsRequest.{ 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 the CallToolRequestHandler switch statement that validates arguments and calls the list_events handler.case "list_events": { const validatedArgs = ListEventsArgsSchema.parse(args); return await handleListEvents(validatedArgs);