calendar-list-events
Retrieve calendar events with customizable filters such as time range, event count, and sorting for efficient event management and scheduling.
Instructions
List calendar events with optional filters
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| calendarId | No | Calendar ID - Available options: 'primary' (Primary Calendar) | primary |
| maxResults | No | Maximum number of events to return | |
| orderBy | No | Order of events | startTime |
| singleEvents | No | Whether to expand recurring events | |
| timeMax | No | Upper bound for event start time (ISO format) | |
| timeMin | No | Lower bound for event start time (ISO format) |
Implementation Reference
- src/calendar.ts:344-406 (handler)The handler function `listEvents` that executes the core logic for listing calendar events using Google Calendar API, applying filters, and formatting the response as Markdown.// List events function export async function listEvents( params: z.infer<ReturnType<typeof listEventsSchema>> ) { try { const auth = createCalendarAuth(); const calendar = google.calendar({ version: "v3", auth }); const listParams: any = { calendarId: params.calendarId, maxResults: params.maxResults, singleEvents: params.singleEvents, orderBy: params.orderBy, }; if (params.timeMin) listParams.timeMin = params.timeMin; if (params.timeMax) listParams.timeMax = params.timeMax; // If no timeMin is specified, default to current time if (!params.timeMin) { listParams.timeMin = new Date().toISOString(); } const response = await calendar.events.list(listParams); const events = response.data.items?.map((event) => ({ id: event.id, summary: event.summary, description: event.description, location: event.location, start: event.start, end: event.end, attendees: event.attendees?.map((a) => ({ email: a.email, responseStatus: a.responseStatus, })), htmlLink: event.htmlLink, status: event.status, created: event.created, updated: event.updated, })); return { content: [ { type: "text" as const, text: formatEventListToMarkdown(events || [], events?.length || 0), }, ], }; } catch (error) { return { content: [ { type: "text" as const, text: `Error listing events: ${ error instanceof Error ? error.message : String(error) }`, }, ], }; } }
- src/calendar.ts:166-194 (schema)Zod schema definition `listEventsSchema` for input validation of the calendar-list-events tool parameters.export const listEventsSchema = () => z.object({ calendarId: z .string() .default("primary") .describe(getCalendarDescription()), timeMin: z .string() .optional() .describe("Lower bound for event start time (ISO format)"), timeMax: z .string() .optional() .describe("Upper bound for event start time (ISO format)"), maxResults: z .number() .min(1) .max(250) .default(10) .describe("Maximum number of events to return"), singleEvents: z .boolean() .default(true) .describe("Whether to expand recurring events"), orderBy: z .enum(["startTime", "updated"]) .default("startTime") .describe("Order of events"), });
- src/index.ts:224-231 (registration)Registration of the 'calendar-list-events' tool in the MCP server using server.tool().server.tool( "calendar-list-events", "List calendar events with optional filters", listEventsSchema().shape, async (params) => { return await listEvents(params); } );
- src/calendar.ts:45-77 (helper)Helper function `formatEventListToMarkdown` used by the handler to format the list of events into a readable Markdown response.function formatEventListToMarkdown(events: any[], totalResults: number): string { if (!events.length) return "# No Upcoming Events\n\nNo events found in the specified time range."; let markdown = `# Upcoming Events (${totalResults})\n\n`; events.forEach((event, index) => { const startDate = event.start?.dateTime ? new Date(event.start.dateTime) : null; const endDate = event.end?.dateTime ? new Date(event.end.dateTime) : null; markdown += `## ${index + 1}. ${event.summary || 'Untitled Event'}\n`; if (startDate) { if (endDate && startDate.toDateString() === endDate.toDateString()) { // Same day event markdown += `When: ${startDate.toLocaleDateString()} ${startDate.toLocaleTimeString()} - ${endDate.toLocaleTimeString()} \n`; } else { markdown += `Start: ${startDate.toLocaleString()} \n`; if (endDate) markdown += `End: ${endDate.toLocaleString()} \n`; } } if (event.location) markdown += `Location: ${event.location} \n`; if (event.description) markdown += `Description: ${event.description} \n`; if (event.attendees && event.attendees.length > 0) { markdown += `Attendees: ${event.attendees.length} people \n`; } if (event.id) markdown += `ID: \`${event.id}\` \n`; markdown += `\n---\n\n`; }); return markdown; }