calcom-mcp

Servidor FastMCP de Cal.com

⚠️ Aviso legal : Este proyecto no está afiliado ni respaldado por Cal.com. Soy un desarrollador independiente y no tengo ninguna relación oficial con Cal.com.

Este proyecto proporciona un servidor FastMCP para interactuar con la API de Cal.com. Permite que los Modelos de Aprendizaje de Idiomas (LLM) utilicen herramientas para conectarse con funcionalidades importantes de Cal.com, como la gestión de tipos de eventos y reservas.

Prerrequisitos

• Python 3.8+
• Una cuenta de Cal.com y una clave API (v2)

Configuración

1. Clonar el repositorio (si corresponde) o descargar los archivos.
   git clone https://github.com/Danielpeter-99/calcom-mcp.git cd calcom-mcp
2. Crear un entorno virtual (recomendado):
   python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
3. Instalar dependencias:
   pip install -r requirements.txt
4. Configurar la clave API de Cal.com: Debe configurar la variable de entorno CALCOM_API_KEY . Puede obtener su clave API en la página de configuración de Cal.com (normalmente en la sección "Desarrollador" o "Seguridad").
   • Linux/macOS:
     export CALCOM_API_KEY="your_actual_api_key_here"
     Para hacerlo permanente, agregue esta línea a su archivo de configuración de shell (por ejemplo, .bashrc , .zshrc ).
   • Ventanas (PowerShell):
     $env:CALCOM_API_KEY="your_actual_api_key_here"
     Para que sea permanente, puedes configurarlo a través de Propiedades del sistema > Variables de entorno.

Ejecución del servidor

Una vez completada la configuración, puedes ejecutar el servidor FastMCP:

El servidor se iniciará en localhost:8010 y debería ver un mensaje indicando que se está ejecutando. Si no se configura CALCOM_API_KEY , se mostrará una advertencia.

Herramientas disponibles

El servidor actualmente proporciona las siguientes herramientas para la interacción LLM:

• get_api_status() : Comprueba si la clave API de Cal.com está configurada en el entorno. Devuelve una cadena que indica el estado.
• list_event_types() : Obtiene una lista de todos los tipos de eventos de Cal.com para la cuenta autenticada. Devuelve un diccionario con la lista de tipos de eventos o un mensaje de error.
• get_bookings(...) : Obtiene una lista de reservas de Cal.com, con filtros opcionales (event_type_id, user_id, status, date_from, date_to, limit). Devuelve un diccionario con la lista de reservas o un mensaje de error.
• create_booking(...) : Crea una nueva reserva en Cal.com para un tipo de evento y un asistente específicos. Requiere parámetros como la hora de inicio, los detalles del asistente y los identificadores del tipo de evento. Devuelve un diccionario con los detalles de la reserva o un mensaje de error.
• list_schedules(...) : Lista todos los horarios disponibles para el usuario autenticado o para un usuario/equipo específico. Filtros opcionales: user_id, team_id, limit. Devuelve un diccionario con la lista de horarios o un mensaje de error.
• list_teams(...) : Lista todos los equipos disponibles para el usuario autenticado. Filtro opcional: límite. Devuelve un diccionario con la lista de equipos o un mensaje de error.
• list_users(...) : Lista todos los usuarios disponibles para la cuenta autenticada. Filtro opcional: límite. Devuelve un diccionario con la lista de usuarios o un mensaje de error.
• list_webhooks(...) : Lista todos los webhooks configurados para la cuenta autenticada. Filtro opcional: límite. Devuelve un diccionario con la lista de webhooks o un mensaje de error.

Nota: Todas las herramientas requieren que la variable de entorno CALCOM_API_KEY esté configurada. Si no lo está, las herramientas devolverán un mensaje de error estructurado.

Uso de herramientas y manejo de errores

• Todas las herramientas devuelven la respuesta de la API (como un diccionario o una cadena) o un mensaje de error estructurado con detalles sobre la falla.
• Los mensajes de error incluyen el tipo de error, el código de estado HTTP (si corresponde) y el texto de respuesta de la API de Cal.com.
• Para obtener mejores resultados, verifique siempre la presencia de una clave error en la respuesta antes de utilizar los datos devueltos.
• Las herramientas están diseñadas para ser sólidas y brindar retroalimentación informativa tanto para llamadas API exitosas como fallidas.

Notas de desarrollo

• La URL base de la API de Cal.com está configurada en https://api.cal.com/v2 .
• La autenticación se gestiona principalmente mediante un token de portador con CALCOM_API_KEY .
• La herramienta create_booking utiliza el encabezado cal-api-version: 2024-08-13 como se especifica en la documentación de Cal.com API v2 para ese punto final.
• El manejo de errores está incluido en las llamadas API para proporcionar respuestas informativas.

🚀 Construido con

Nota de seguridad importante

Nunca codifique su CALCOM_API_KEY directamente en el código fuente. Utilice siempre las variables de entorno descritas en las instrucciones de configuración para proteger su clave API.