Google Services MCP Server

Instructions

Implementation Reference

• src/calendar.ts:409-463 (handler)

  The main handler function that retrieves a specific calendar event using Google Calendar API's events.get method, extracts relevant details, and formats the response as Markdown using formatEventToMarkdown.

  export async function getEvent(
    params: z.infer<ReturnType<typeof getEventSchema>>
  ) {
    try {
      const auth = createCalendarAuth();
      const calendar = google.calendar({ version: "v3", auth });
  
      const response = await calendar.events.get({
        calendarId: params.calendarId,
        eventId: params.eventId,
      });
  
      const event = response.data;
      const eventDetail = {
        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,
          displayName: a.displayName,
          responseStatus: a.responseStatus,
        })),
        creator: event.creator,
        organizer: event.organizer,
        htmlLink: event.htmlLink,
        status: event.status,
        created: event.created,
        updated: event.updated,
        recurrence: event.recurrence,
      };
  
      return {
        content: [
          {
            type: "text" as const,
            text: formatEventToMarkdown(eventDetail),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Error getting event: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
      };
    }
  }

• src/calendar.ts:196-203 (schema)

  Zod schema defining input parameters for the calendar-get-event tool: eventId (required) and calendarId (optional, defaults to 'primary').

  export const getEventSchema = () =>
    z.object({
      eventId: z.string().describe("Event ID"),
      calendarId: z
        .string()
        .default("primary")
        .describe(getCalendarDescription()),
    });

• src/index.ts:233-240 (registration)

  Registers the 'calendar-get-event' tool with the MCP server inside registerCalendarTools function, providing name, description, input schema from getEventSchema, and handler that delegates to getEvent.

  server.tool(
    "calendar-get-event",
    "Get a specific calendar event by ID",
    getEventSchema().shape,
    async (params) => {
      return await getEvent(params);
    }
  );

• src/calendar.ts:9-43 (helper)

  Helper function used by getEvent to format the retrieved event data into a readable Markdown string for the tool response.

  function formatEventToMarkdown(event: any): string {
    let markdown = `# ${event.summary || 'Untitled Event'}\n\n`;
    
    if (event.description) markdown += `${event.description}\n\n`;
    
    const startDate = event.start?.dateTime ? new Date(event.start.dateTime) : null;
    const endDate = event.end?.dateTime ? new Date(event.end.dateTime) : null;
    
    if (startDate) {
      markdown += `Start: ${startDate.toLocaleString()}  \n`;
    }
    if (endDate) {
      markdown += `End: ${endDate.toLocaleString()}  \n`;
    }
    
    if (event.location) markdown += `Location: ${event.location}  \n`;
    
    if (event.attendees && event.attendees.length > 0) {
      markdown += `Attendees: ${event.attendees.map((a: any) => {
        let attendee = a.email || a;
        if (a.responseStatus) {
          const status = a.responseStatus === 'accepted' ? '✅' : 
                       a.responseStatus === 'declined' ? '❌' : 
                       a.responseStatus === 'tentative' ? '❓' : '⏳';
          attendee += ` ${status}`;
        }
        return attendee;
      }).join(', ')}  \n`;
    }
    
    if (event.htmlLink) markdown += `Calendar Link: [View Event](${event.htmlLink})  \n`;
    if (event.id) markdown += `Event ID: \`${event.id}\`  \n`;
    
    return markdown;
  }