calendar-list-events
Retrieve calendar events with filters for date range, calendar selection, and sorting to manage your schedule effectively.
Instructions
List calendar events with optional filters
Input 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) |
Input Schema (JSON Schema)
{
"properties": {
"calendarId": {
"default": "primary",
"description": "Calendar ID - Available options: 'primary' (Primary Calendar)",
"type": "string"
},
"maxResults": {
"default": 10,
"description": "Maximum number of events to return",
"maximum": 250,
"minimum": 1,
"type": "number"
},
"orderBy": {
"default": "startTime",
"description": "Order of events",
"enum": [
"startTime",
"updated"
],
"type": "string"
},
"singleEvents": {
"default": true,
"description": "Whether to expand recurring events",
"type": "boolean"
},
"timeMax": {
"description": "Upper bound for event start time (ISO format)",
"type": "string"
},
"timeMin": {
"description": "Lower bound for event start time (ISO format)",
"type": "string"
}
},
"type": "object"
}
Implementation Reference
- src/calendar.ts:344-406 (handler)The main handler function that implements the calendar-list-events tool. It uses the Google Calendar API to list events with optional filters, processes the response, formats it as markdown using formatEventListToMarkdown, and returns the content.// 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)The Zod schema definition for input parameters of the calendar-list-events tool, defining optional filters like time range, max results, etc., with dynamic description for calendarId.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)The MCP server.tool registration for 'calendar-list-events', providing name, description, schema from listEventsSchema, and handler that calls listEvents.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 used by the listEvents handler to format the list of events into a readable markdown list for the tool 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; }