Cal.com Calendar MCP Server

Instructions

Implementation Reference

• index.ts:259-293 (handler)

  Core handler function that executes the calcom_add_appointment tool logic: performs rate limiting, makes POST request to Cal.com API to create booking, and returns success message.

  async function addAppointment(
    eventTypeId: number, 
    startTime: string, 
    endTime: string, 
    name: string, 
    email: string, 
    notes?: string
  ) {
    checkRateLimit();
    
    try {
      const response = await calComApiClient.post('/bookings', {
        eventTypeId,
        start: new Date(startTime).toISOString(),
        end: new Date(endTime).toISOString(),
        name,
        email,
        notes,
      });
      
      const booking = response.data;
      
      return `Appointment created successfully! Booking ID: ${booking.id}
  Event Type: ${booking.eventTypeId}
  Start Time: ${booking.startTime}
  End Time: ${booking.endTime}
  Attendee: ${name} (${email})
  ${notes ? `Notes: ${notes}` : ""}`;
    } catch (error: any) {
      if (axios.isAxiosError(error)) {
        throw new Error(`Failed to create appointment: ${error.response?.data?.message || error.message}`);
      }
      throw new Error(`Failed to create appointment: ${String(error)}`);
    }
  }

• index.ts:12-48 (schema)

  Tool definition including name, description, and input schema for calcom_add_appointment.

  const ADD_APPOINTMENT_TOOL: Tool = {
    name: "calcom_add_appointment",
    description:
      "Creates a new appointment in Cal.com calendar. " +
      "Use this for scheduling new meetings or appointments. " +
      "Requires event type ID, start time, end time, name, email, and optional notes. ",
    inputSchema: {
      type: "object",
      properties: {
        eventTypeId: {
          type: "number",
          description: "The Cal.com event type ID"
        },
        startTime: {
          type: "string",
          description: "Start time in ISO format (YYYY-MM-DDTHH:mm:ss.sssZ)"
        },
        endTime: {
          type: "string",
          description: "End time in ISO format (YYYY-MM-DDTHH:mm:ss.sssZ)"
        },
        name: {
          type: "string",
          description: "Attendee's name"
        },
        email: {
          type: "string",
          description: "Attendee's email"
        },
        notes: {
          type: "string",
          description: "Optional notes for the appointment",
        }
      },
      required: ["eventTypeId", "startTime", "endTime", "name", "email"],
    },
  };

• index.ts:379-386 (registration)

  Registers the calcom_add_appointment tool (via ADD_APPOINTMENT_TOOL) in the ListToolsRequestSchema handler.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      ADD_APPOINTMENT_TOOL, 
      UPDATE_APPOINTMENT_TOOL, 
      DELETE_APPOINTMENT_TOOL, 
      LIST_APPOINTMENTS_TOOL
    ],
  }));

• index.ts:397-407 (handler)

  Tool dispatch handler in CallToolRequestSchema that validates arguments and calls the addAppointment function.

  case "calcom_add_appointment": {
    if (!isCalComAddAppointmentArgs(args)) {
      throw new Error("Invalid arguments for calcom_add_appointment");
    }
    const { eventTypeId, startTime, endTime, name, email, notes } = args;
    const result = await addAppointment(eventTypeId, startTime, endTime, name, email, notes);
    return {
      content: [{ type: "text", text: result }],
      isError: false,
    };
  }

• index.ts:204-221 (schema)

  Type guard function for validating input arguments to calcom_add_appointment.

  function isCalComAddAppointmentArgs(args: unknown): args is { 
    eventTypeId: number; 
    startTime: string; 
    endTime: string; 
    name: string; 
    email: string; 
    notes?: string;
  } {
    return (
      typeof args === "object" &&
      args !== null &&
      "eventTypeId" in args &&
      "startTime" in args &&
      "endTime" in args &&
      "name" in args &&
      "email" in args
    );
  }