Cal.com Calendar MCP Server

Instructions

Implementation Reference

• index.ts:433-443 (handler)

  Handler case in CallToolRequestSchema that validates arguments and invokes the listAppointments function to execute the tool logic.

  case "calcom_list_appointments": {
    if (!isCalComListAppointmentsArgs(args)) {
      throw new Error("Invalid arguments for calcom_list_appointments");
    }
    const { startDate, endDate } = args;
    const result = await listAppointments(startDate, endDate);
    return {
      content: [{ type: "text", text: result }],
      isError: false,
    };
  }

• index.ts:344-376 (helper)

  Core helper function that performs the API call to Cal.com to fetch and format appointments within the given date range.

  async function listAppointments(startDate: string, endDate: string) {
    checkRateLimit();
    
    try {
      const response = await calComApiClient.get('/bookings', {
        params: {
          dateFrom: startDate,
          dateTo: endDate,
        }
      });
      
      const bookings = response.data;
      
      if (bookings.length === 0) {
        return "No appointments found for the selected date range.";
      }
      
      return bookings.map((booking: any) => `
  ID: ${booking.id}
  Event Type: ${booking.eventTypeId}
  Status: ${booking.status}
  Start Time: ${booking.startTime}
  End Time: ${booking.endTime}
  Attendees: ${booking.attendees.map((a: any) => `${a.name} (${a.email})`).join(", ")}
  ${booking.notes ? `Notes: ${booking.notes}` : ""}
  `).join("\n---\n");
    } catch (error: any) {
      if (axios.isAxiosError(error)) {
        throw new Error(`Failed to list appointments: ${error.response?.data?.message || error.message}`);
      }
      throw new Error(`Failed to list appointments: ${String(error)}`);
    }
  }

• index.ts:247-257 (schema)

  Input argument validator (type guard) ensuring required startDate and endDate are present.

  function isCalComListAppointmentsArgs(args: unknown): args is { 
    startDate: string; 
    endDate: string;
  } {
    return (
      typeof args === "object" &&
      args !== null &&
      "startDate" in args &&
      "endDate" in args
    );
  }

• index.ts:379-386 (registration)

  Registers the calcom_list_appointments tool (via LIST_APPOINTMENTS_TOOL) in the ListToolsRequestSchema handler.

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

• index.ts:102-122 (schema)

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

  const LIST_APPOINTMENTS_TOOL: Tool = {
    name: "calcom_list_appointments",
    description:
      "Lists appointments from Cal.com calendar. " +
      "Can be filtered by date range. " +
      "Returns a list of appointments with their details. ",
    inputSchema: {
      type: "object",
      properties: {
        startDate: {
          type: "string",
          description: "Start date in YYYY-MM-DD format"
        },
        endDate: {
          type: "string",
          description: "End date in YYYY-MM-DD format"
        }
      },
      required: ["startDate", "endDate"],
    }
  };