Cal.com MCP
oficialConecta clientes de IA con la programación de Cal.com a través del Protocolo de Contexto del Modelo usando el servidor alojado en mcp.cal.com o una instancia local.
¿Qué puedes hacer con Cal Com MCP?
- Gestionar reservas — Pide a tu asistente que enumere, cree, reprograme, cancele o confirme reservas, y que añada o consulte asistentes.
- Consultar disponibilidad — Obtén franjas horarias disponibles, horarios ocupados de los calendarios conectados y tus calendarios y aplicaciones de videoconferencia conectados.
- Configurar tipos de evento — Crea, actualiza, duplica o elimina tipos de evento, y consulta su configuración, los ajustes de programación y el historial de cambios.
- Trabajar con horarios — Enumera, crea, actualiza o elimina horarios y consulta tu horario predeterminado.
- Gestionar equipos y organizaciones — Consulta equipos, gestiona las membresías e invitaciones de equipos y gestiona las membresías y los atributos de organizaciones.
- Buscar en el catálogo de la API — Encuentra, describe y ejecuta cualquier operación de la API v2 de Cal.com mediante las metaherramientas del catálogo.
Documentación
Servidor MCP
Conecta clientes de IA con la programación de Cal.com a través del Model Context Protocol usando el servidor alojado en mcp.cal.com o una instancia local.
El servidor MCP de Cal.com integra la API v2 de Cal.com en el Model Context Protocol, lo que te permite gestionar reservas, tipos de evento, horarios y mucho más mediante lenguaje natural en cualquier cliente compatible con MCP.
Servidor alojado (mcp.cal.com)
La forma más rápida de empezar es conectar tu cliente MCP directamente a mcp.cal.com. El servidor alojado usa el transporte Streamable HTTP con autenticación OAuth 2.1; tu cliente gestiona automáticamente el flujo de autorización.
Conecta tu cliente
Configura la URL del servidor alojado en tu cliente MCP:
https://mcp.cal.com/mcp
La primera vez que te conectes, tu cliente te guiará por un flujo de autorización OAuth en el que concederás al servidor acceso a tu cuenta de Cal.com. No se necesita ninguna clave de API. Cualquier cliente MCP puede conectarse: los clientes se registran dinámicamente mediante POST /oauth/register o se identifican con un documento de metadatos de cliente (una URL de client_id de https). Antes de iniciar sesión en Cal.com, verás una página de consentimiento que indica el nombre del cliente y el host al que volverás.
[!NOTE]
La pantalla de consentimiento también solicita permisos de equipo para crear, editar y eliminar tipos de evento de equipo, así como para ver y gestionar membresías de equipo, de modo que tu cliente de IA pueda configurar tipos de evento de equipo y añadir personas a los equipos. También solicita los permisos del perfil de la organización, para que el cliente de IA de un administrador de la organización pueda enumerar, crear, editar y eliminar los equipos de la organización. Cal.com sigue comprobando tu rol y tus permisos en el equipo en cada llamada. También solicita permiso para ver, añadir, cambiar el nombre y eliminar tus contactos personales (
CONTACT_READ,CONTACT_WRITE). Si te conectaste antes de que se añadieran estos permisos, desconecta y vuelve a conectar el servidor para concederlos.
[tab] Claude Desktop
Añade lo siguiente a tu
claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json- Windows:
%APPDATA%\Claude\claude_desktop_config.json{ "mcpServers": { "calcom": { "url": "https://mcp.cal.com/mcp" } } }
[tab] Cursor
Abre Settings → MCP y añade un servidor nuevo con la URL
https://mcp.cal.com/mcp, o añádelo a tu.cursor/mcp.json:{ "mcpServers": { "calcom": { "url": "https://mcp.cal.com/mcp" } } }
[tab] VS Code
Añade el servidor a la configuración MCP de VS Code:
{ "mcpServers": { "calcom": { "url": "https://mcp.cal.com/mcp" } } }
[tab] fx
Añade lo siguiente a tu
~/.fx/mcp.json:{ "mcp": { "calcom": { "type": "http", "url": "https://mcp.cal.com/mcp" } } }Luego ejecuta
/mcp auth calcom --openen fx para autorizar. Consulta la documentación de MCP de fx para obtener información sobre transportes, opciones de autenticación y detección de herramientas.
[tab] Grok
Grok se conecta a través del bot de Cal.com en lugar de una configuración JSON. En Settings → Developer → MCP, selecciona Grok Bot en Client setup y, a continuación, escanea el código QR o haz clic en Add Bot para abrir el bot de Cal.com en Grok.
Servidor autohospedado (stdio)
Si prefieres ejecutar el servidor localmente, puedes usar el transporte stdio con una clave de API. Esto resulta útil para el desarrollo o cuando quieres tener control total sobre el servidor.
Requisitos previos
- Node.js >= 18
- Una clave de API de Cal.com: genera una en Settings → Developer → API Keys
Conecta tu cliente
Añade lo siguiente a la configuración de tu cliente MCP:
{
"mcpServers": {
"calcom": {
"command": "npx",
"args": ["@calcom/cal-mcp@latest"],
"env": {
"CAL_API_KEY": "cal_live_xxxx"
}
}
}
}
Sustituye cal_live_xxxx por tu clave de API real.
[!WARNING]
Nunca compartas ni confirmes tu clave de API en el repositorio. Si queda expuesta, rótala inmediatamente en tu configuración de Cal.com.
Ejecuta el servidor HTTP con Docker Compose
Para autohospedar el servidor Streamable HTTP con OAuth, usa el archivo apps/mcp/docker-compose.yml del repositorio de Cal.com. Ejecuta el servidor MCP y su base de datos PostgreSQL detrás de un proxy Caddy en los puertos 80 y 443.
Configura MCP_POSTGRES_PASSWORD antes de iniciarlo. Compose no se iniciará si no está configurada. Como la contraseña también se incluye en la cadena de conexión de la base de datos del servidor, usa únicamente caracteres seguros para URL.
export MCP_POSTGRES_PASSWORD="$(openssl rand -hex 24)"
docker compose -f apps/mcp/docker-compose.yml up -d
PostgreSQL no se publica en ningún puerto del host. Solo el servidor MCP puede acceder a ella a través de la red de Compose. Para conectarte tú mismo a la base de datos, usa docker compose -f apps/mcp/docker-compose.yml exec postgres psql -U mcp mcp.
[!NOTE]
PostgreSQL solo lee la contraseña cuando crea el volumen de datos por primera vez. Si creaste el volumen con una versión anterior del archivo de Compose, la contraseña sigue siendo
mcp. ConfiguraMCP_POSTGRES_PASSWORD=mcpo cambia la contraseña conALTER USER mcp PASSWORD '...'y establece el nuevo valor.
Conjuntos de herramientas
Puedes limitar las herramientas que registra el servidor para una sesión añadiendo un parámetro de consulta toolsets a la URL del servidor:
https://mcp.cal.com/mcp?toolsets=bookings,availability
Conjuntos de herramientas válidos: profile, event-types, events, bookings, availability, schedules, calendars, contacts, discover, teams, organizations, routing-forms, catalog (las metaherramientas find_api_operation / describe_api_operation / call_api_operation). Los nombres desconocidos se rechazan con 400 invalid_request. Si omites el parámetro, se registran todas las herramientas; las herramientas locales get_app_link y search_docs siempre se registran, independientemente de la selección. Para un servidor stdio autohospedado, configura MCP_TOOLSETS en su lugar.
Vistas interactivas (MCP Apps)
En los clientes compatibles con MCP Apps, get_availability y get_bookings también muestran una vista interactiva en el chat, para que puedas elegir horarios y gestionar reservas haciendo clic en lugar de escribir:
- Selector de horarios (
get_availability): muestra los horarios disponibles agrupados por día. Usa las flechas para ir a fechas anteriores o posteriores, haz clic en un horario, introduce el nombre y el correo electrónico del asistente y haz clic en Book. Cuando el asistente busca un nuevo horario para una reserva existente, al hacer clic en un horario se ofrece la opción Move booking here. - Reservas (
get_bookings): muestra una tarjeta por reserva con su horario y asistentes. Las reservas próximas incluyen las opciones Join (si la reserva tiene un enlace de reunión), Reschedule, que muestra los horarios disponibles de la semana siguiente para elegir, y Cancel, que primero te pide confirmar en la tarjeta.
Los horarios se muestran en la zona horaria que indica tu cliente, y las vistas siguen su tema claro u oscuro. Las acciones se ejecutan mediante las mismas herramientas create_booking, reschedule_booking y cancel_booking de tu conexión actual, y se informa al asistente de lo que hiciste.
[!NOTE]
Las vistas solo están disponibles cuando están habilitados los conjuntos de herramientas
bookingsyavailability, que se habilitan de forma predeterminada si no pasastoolsets. Los clientes que no admiten MCP Apps reciben los mismos resultados de texto que antes.
Suscripciones a eventos (MCP Events)
El servidor alojado admite MCP Events, por lo que los clientes que usan la versión de protocolo 2026-07-28 pueden recibir notificaciones cuando ocurre algo en tu cuenta de Cal.com, en lugar de consultar periódicamente. El servidor anuncia la capacidad events y gestiona tres métodos:
events/list: devuelve los eventos a los que puedes suscribirte, comobooking.created,booking.rescheduled,booking.cancelled,meeting.endedyrecording.ready, cada uno con un esquema de entrada y un esquema de carga útil.events/subscribe: suscribe una URL de devolución de llamada a un evento. La URL de devolución de llamada debe ser una URL HTTPS pública, ydelivery.secretdebe ser un secretowhsec_. Antes de guardar la suscripción, el servidor envía una solicitud de verificación firmada con un valorchallengeque tu endpoint debe devolver en su respuesta JSON. Si vuelves a suscribirte con la misma URL, evento y argumentos, se actualiza la suscripción existente.events/unsubscribe: elimina una de tus suscripciones. Si lo llamas para una suscripción que ya no existe, la operación se completa correctamente.
Las entregas se firman con Standard Webhooks usando tu secreto whsec_. Las suscripciones caducan después de 7 días de forma predeterminada; configura ttlMs para solicitar una duración de entre 1 hora y 30 días.
Tu primera suscripción crea un webhook de Cal.com en tu cuenta que envía eventos a la ruta POST /events/calcom/<ref> del servidor, y al eliminar la última suscripción se elimina el webhook. No debes llamar a esta ruta directamente.
[!NOTE]
MCP Events solo se ofrece a través del transporte Streamable HTTP, no mediante el servidor stdio autohospedado. No está relacionado con el conjunto de herramientas
events, que gestiona las páginas RSVP de Cal Events.
Herramientas disponibles
El servidor MCP expone 85 herramientas organizadas por categoría:
Enlaces a la aplicación
| Herramienta | Descripción |
|---|---|
get_app_link | Crea una URL que abre una reserva, un tipo de evento, un horario, un equipo, un formulario de enrutamiento o una página de configuración en la aplicación web de Cal.com |
Documentación
| Herramienta | Descripción |
|---|---|
search_docs | Busca en la documentación del producto Cal.com; devuelve páginas ordenadas por relevancia con un extracto del resultado principal |
Perfil de usuario
| Herramienta | Descripción |
|---|---|
get_me | Obtiene el perfil del usuario autenticado |
update_me | Actualiza tu perfil de usuario |
Tipos de evento
| Herramienta | Descripción |
|---|---|
get_event_types | Enumera todos los tipos de evento |
get_event_type | Obtiene un tipo de evento específico por ID |
create_event_type | Crea un tipo de evento nuevo |
update_event_type | Actualiza un tipo de evento |
delete_event_type | Elimina un tipo de evento |
duplicate_event_type | Duplica un tipo de evento de un equipo de la organización en el mismo equipo o en otro equipo de la organización |
get_event_type_settings | Obtiene la configuración de un tipo de evento |
get_event_type_history | Obtiene el historial de cambios de un tipo de evento |
get_scheduling_config | Obtiene la configuración de programación de un tipo de evento |
get_crm_sync_errors | Obtiene los errores de sincronización de CRM de un tipo de evento |
Eventos
Cal Events son páginas RSVP con fecha fija disponibles en cal.com/{slug}; no son tipos de evento ni eventos de calendario. get_events y get_event necesitan el permiso OAuth EVENT_READ, y invite_cal_event_guests necesita EVENT_WRITE.
| Herramienta | Descripción |
|---|---|
get_events | Enumera los eventos que organizas o coorganizas, del más reciente al más antiguo; admite limit (máximo 250), paginación cursor y un filtro slug |
get_event | Obtiene un evento por uuid |
invite_cal_event_guests | Envía una invitación por correo electrónico a cada dirección, a cada uno de tus contactos por ID (contactIds) o a todos los contactos con una de tus etiquetas de contacto (contactTagIds); los contactos necesitan la función contacts; informa de lo ocurrido con cada dirección |
Reservas
| Herramienta | Descripción |
|---|---|
get_bookings | Enumera las reservas con filtros opcionales |
get_booking | Obtiene una reserva específica por UID |
create_booking | Crea una reserva nueva |
reschedule_booking | Reprograma una reserva |
cancel_booking | Cancela una reserva |
confirm_booking | Confirma una reserva pendiente |
mark_booking_absent | Marca una ausencia en una reserva |
get_booking_attendees | Obtiene todos los asistentes de una reserva |
add_booking_attendee | Añade un asistente a una reserva |
get_booking_attendee | Obtiene un asistente específico |
get_booking_routing_trace | Obtiene el registro de enrutamiento de una reserva |
get_org_team_bookings | Obtiene las reservas de un equipo de la organización |
get_org_user_bookings | Obtiene las reservas de un usuario de la organización |
Horarios
| Herramienta | Descripción |
|---|---|
get_schedules | Enumera todos los horarios |
get_schedule | Obtiene un horario específico por ID |
create_schedule | Crea un horario nuevo |
update_schedule | Actualiza un horario |
delete_schedule | Elimina un horario |
get_default_schedule | Obtiene tu horario predeterminado |
Disponibilidad y calendarios
| Herramienta | Descripción |
|---|---|
get_availability | Obtiene los horarios disponibles |
get_busy_times | Obtiene los horarios ocupados de los calendarios |
get_connected_calendars | Enumera los calendarios conectados |
get_conferencing_apps | Enumera las aplicaciones de videoconferencia |
Contactos
Tus contactos personales y sus etiquetas de la página Contactos; nunca miembros de equipos u organizaciones. Las listas necesitan el ámbito OAuth CONTACT_READ y las escrituras, CONTACT_WRITE. Las etiquetas se comparten con tus enlaces.
| Herramienta | Descripción |
|---|---|
list_contacts | Enumerar tus contactos, 50 por página, opcionalmente solo los que tengan determinadas etiquetas, e indicar si cada uno está en Cal y puede unirse a una reunión grupal |
add_contact | Añadir un contacto por correo electrónico, con un nombre opcional |
update_contact | Actualizar el nombre de un contacto; no se puede cambiar el nombre de un contacto que esté en Cal |
remove_contact | Eliminar un contacto y sus etiquetas |
list_contact_tags | Enumerar tus etiquetas, 50 por página, e indicar cuántos contactos tienen cada una |
create_contact_tag | Crear una etiqueta sin asignarla a ningún contacto |
add_contact_tag | Asignar una etiqueta a un contacto |
remove_contact_tag | Quitar una etiqueta de un contacto; la etiqueta en sí permanece |
Descubrir
Anuncios publicados en Discover, que se pueden buscar o consultar mediante los identificadores devueltos por una búsqueda y que requieren el ámbito OAuth EVENT_TYPE_READ; llamadas y reservas en línea en negocios encontrados en la web, y solicitudes para recibir un aviso cuando se incorpore un proveedor, que requieren PROFILE_WRITE.
| Herramienta | Descripción |
|---|---|
search_listings | Buscar anuncios por categoría, texto libre, zona, precio, duración y una franja horaria disponible, con el enlace de reserva de cada anuncio; si no hay resultados en la zona, buscar negocios en la web |
get_discover_listings | Consultar hasta 50 anuncios tal como aparecen en sus fichas públicas, opcionalmente con la primera franja disponible de cada uno en los próximos 7 días |
call_business_to_book | Pedir a Cal que llame a un negocio que search_listings encontró en la web para reservar un servicio, una vez que el usuario lo apruebe; devuelve la página de la llamada para hacerle seguimiento |
book_online | Pedir al agente de reservas de Cal que reserve por su cuenta un negocio que search_listings encontró en la web, en la página de reservas del negocio, una vez que el usuario lo apruebe; devuelve la página del proceso, donde el usuario elige una opción y aprueba el precio y las condiciones |
record_service_request | Solicitar que se te envíe un correo a la dirección de tu cuenta cuando se incorpore un proveedor para un servicio que no tiene anuncios en Discover; volver a solicitar lo mismo en la misma región dentro de 90 días no cambia nada |
Equipos y membresías
| Herramienta | Descripción |
|---|---|
get_my_teams | Obtener los equipos a los que perteneces |
get_org_teams | Obtener los equipos de la organización |
create_team_invite | Invitar a alguien a un equipo |
create_team_membership | Crear una membresía de equipo |
get_team_memberships | Obtener todas las membresías de equipo |
get_team_membership | Obtener una membresía de equipo |
update_team_membership | Actualizar una membresía de equipo |
delete_team_membership | Eliminar una membresía de equipo |
Organizaciones
| Herramienta | Descripción |
|---|---|
get_org_memberships | Obtener todas las membresías de organización |
create_org_membership | Crear una membresía de organización |
get_org_membership | Obtener una membresía de organización |
update_org_membership | Actualizar una membresía de organización |
delete_org_membership | Eliminar una membresía de organización |
get_org_attributes | Obtener los atributos de la organización |
get_org_attribute | Obtener un atributo de la organización |
get_attribute_options | Obtener las opciones de un atributo |
get_user_attributes | Obtener los atributos asignados a un usuario |
assign_attribute_to_user | Asignar un atributo a un usuario |
update_user_attribute | Actualizar un atributo asignado a un usuario |
unassign_attribute_from_user | Quitar la asignación de un atributo a un usuario |
get_user_attribute_history | Obtener el historial de asignaciones de atributos de un usuario |
Formularios de enrutamiento
| Herramienta | Descripción |
|---|---|
calculate_routing_form_slots | Calcular franjas horarias según la respuesta al formulario de enrutamiento |
get_org_routing_forms | Obtener los formularios de enrutamiento de la organización |
get_org_routing_form_responses | Obtener las respuestas a los formularios de enrutamiento |
get_team_routing_forms | Obtener los formularios de enrutamiento del equipo |
create_routing_form | Crear un formulario de enrutamiento de equipo que comience con una ruta alternativa |
get_routing_form | Obtener las preguntas y rutas de un formulario de enrutamiento de equipo |
get_routing_form_history | Obtener el historial de cambios de un formulario de enrutamiento de equipo, del más reciente al más antiguo: quién cambió qué y cuándo; admite limit (máximo 50) y paginación cursor |
edit_routing_form_routes | Previsualizar y aplicar cambios a las rutas de un formulario de enrutamiento de equipo |
edit_routing_form_fields | Previsualizar y aplicar cambios a las preguntas de un formulario de enrutamiento de equipo |
Catálogo de API
| Herramienta | Descripción |
|---|---|
find_api_operation | Buscar en el catálogo completo de operaciones de API v2 |
describe_api_operation | Obtener el esquema de entrada de una operación de API |
call_api_operation | Ejecutar cualquier operación de API v2 del catálogo |
Ejemplos de indicaciones
Una vez conectado, puedes interactuar con Cal.com usando lenguaje natural:
- "¿Qué reservas tengo esta semana?"
- "Crea un tipo de evento de 30 minutos llamado 'Charla rápida'"
- "Cancela mi reunión con John de mañana"
- "Muéstrame mis franjas disponibles para el próximo lunes"
- "Reprograma mi reunión de las 2 p. m. para el jueves a las 3 p. m."
- "¿Qué tipos de eventos tengo?"
Recursos relacionados
- Guía de agentes de IA — crea agentes de IA usando directamente la API de Cal.com
- Referencia de API v2 — documentación completa de los endpoints de la API
Esta documentación se crea y aloja en Mintlify, una plataforma de documentación para desarrolladores.
