Cal.com MCP

oficial

Conecta 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 --open en 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.

The MCP page in Cal.com developer settings with Grok Bot selected under Client setup, showing a QR code and an Add Bot button

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

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. Configura MCP_POSTGRES_PASSWORD=mcp o cambia la contraseña con ALTER 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 bookings y availability, que se habilitan de forma predeterminada si no pasas toolsets. 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, como booking.created, booking.rescheduled, booking.cancelled, meeting.ended y recording.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, y delivery.secret debe ser un secreto whsec_. Antes de guardar la suscripción, el servidor envía una solicitud de verificación firmada con un valor challenge que 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

HerramientaDescripción
get_app_linkCrea 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

HerramientaDescripción
search_docsBusca en la documentación del producto Cal.com; devuelve páginas ordenadas por relevancia con un extracto del resultado principal

Perfil de usuario

HerramientaDescripción
get_meObtiene el perfil del usuario autenticado
update_meActualiza tu perfil de usuario

Tipos de evento

HerramientaDescripción
get_event_typesEnumera todos los tipos de evento
get_event_typeObtiene un tipo de evento específico por ID
create_event_typeCrea un tipo de evento nuevo
update_event_typeActualiza un tipo de evento
delete_event_typeElimina un tipo de evento
duplicate_event_typeDuplica 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_settingsObtiene la configuración de un tipo de evento
get_event_type_historyObtiene el historial de cambios de un tipo de evento
get_scheduling_configObtiene la configuración de programación de un tipo de evento
get_crm_sync_errorsObtiene 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.

HerramientaDescripción
get_eventsEnumera 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_eventObtiene un evento por uuid
invite_cal_event_guestsEnví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

HerramientaDescripción
get_bookingsEnumera las reservas con filtros opcionales
get_bookingObtiene una reserva específica por UID
create_bookingCrea una reserva nueva
reschedule_bookingReprograma una reserva
cancel_bookingCancela una reserva
confirm_bookingConfirma una reserva pendiente
mark_booking_absentMarca una ausencia en una reserva
get_booking_attendeesObtiene todos los asistentes de una reserva
add_booking_attendeeAñade un asistente a una reserva
get_booking_attendeeObtiene un asistente específico
get_booking_routing_traceObtiene el registro de enrutamiento de una reserva
get_org_team_bookingsObtiene las reservas de un equipo de la organización
get_org_user_bookingsObtiene las reservas de un usuario de la organización

Horarios

HerramientaDescripción
get_schedulesEnumera todos los horarios
get_scheduleObtiene un horario específico por ID
create_scheduleCrea un horario nuevo
update_scheduleActualiza un horario
delete_scheduleElimina un horario
get_default_scheduleObtiene tu horario predeterminado

Disponibilidad y calendarios

HerramientaDescripción
get_availabilityObtiene los horarios disponibles
get_busy_timesObtiene los horarios ocupados de los calendarios
get_connected_calendarsEnumera los calendarios conectados
get_conferencing_appsEnumera 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.

HerramientaDescripción
list_contactsEnumerar 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_contactAñadir un contacto por correo electrónico, con un nombre opcional
update_contactActualizar el nombre de un contacto; no se puede cambiar el nombre de un contacto que esté en Cal
remove_contactEliminar un contacto y sus etiquetas
list_contact_tagsEnumerar tus etiquetas, 50 por página, e indicar cuántos contactos tienen cada una
create_contact_tagCrear una etiqueta sin asignarla a ningún contacto
add_contact_tagAsignar una etiqueta a un contacto
remove_contact_tagQuitar 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.

HerramientaDescripción
search_listingsBuscar 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_listingsConsultar 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_bookPedir 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_onlinePedir 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_requestSolicitar 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

HerramientaDescripción
get_my_teamsObtener los equipos a los que perteneces
get_org_teamsObtener los equipos de la organización
create_team_inviteInvitar a alguien a un equipo
create_team_membershipCrear una membresía de equipo
get_team_membershipsObtener todas las membresías de equipo
get_team_membershipObtener una membresía de equipo
update_team_membershipActualizar una membresía de equipo
delete_team_membershipEliminar una membresía de equipo

Organizaciones

HerramientaDescripción
get_org_membershipsObtener todas las membresías de organización
create_org_membershipCrear una membresía de organización
get_org_membershipObtener una membresía de organización
update_org_membershipActualizar una membresía de organización
delete_org_membershipEliminar una membresía de organización
get_org_attributesObtener los atributos de la organización
get_org_attributeObtener un atributo de la organización
get_attribute_optionsObtener las opciones de un atributo
get_user_attributesObtener los atributos asignados a un usuario
assign_attribute_to_userAsignar un atributo a un usuario
update_user_attributeActualizar un atributo asignado a un usuario
unassign_attribute_from_userQuitar la asignación de un atributo a un usuario
get_user_attribute_historyObtener el historial de asignaciones de atributos de un usuario

Formularios de enrutamiento

HerramientaDescripción
calculate_routing_form_slotsCalcular franjas horarias según la respuesta al formulario de enrutamiento
get_org_routing_formsObtener los formularios de enrutamiento de la organización
get_org_routing_form_responsesObtener las respuestas a los formularios de enrutamiento
get_team_routing_formsObtener los formularios de enrutamiento del equipo
create_routing_formCrear un formulario de enrutamiento de equipo que comience con una ruta alternativa
get_routing_formObtener las preguntas y rutas de un formulario de enrutamiento de equipo
get_routing_form_historyObtener 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_routesPrevisualizar y aplicar cambios a las rutas de un formulario de enrutamiento de equipo
edit_routing_form_fieldsPrevisualizar y aplicar cambios a las preguntas de un formulario de enrutamiento de equipo

Catálogo de API

HerramientaDescripción
find_api_operationBuscar en el catálogo completo de operaciones de API v2
describe_api_operationObtener el esquema de entrada de una operación de API
call_api_operationEjecutar 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

Esta documentación se crea y aloja en Mintlify, una plataforma de documentación para desarrolladores.