Google Calendar MCP Server

Instructions

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);