Cal.com MCP

официальный

Подключайте AI-клиенты к планировщику Cal.com через протокол Model Context Protocol, используя размещённый сервер на mcp.cal.com или локальный экземпляр.

Что можно делать с Cal Com MCP?

  • Управление бронированиями — Попросите ассистента перечислить, создать, перенести, отменить или подтвердить бронирования, а также добавить или просмотреть участников.
  • Проверка доступности — Узнайте о свободных временных интервалах, занятых периодах в подключённых календарях, а также о подключённых календарях и приложениях для видеоконференций.
  • Настройка типов событий — Создавайте, обновляйте, дублируйте или удаляйте типы событий, а также просматривайте их настройки, конфигурацию расписания и историю изменений.
  • Работа с расписаниями — Просматривайте, создавайте, обновляйте или удаляйте расписания и получайте расписание по умолчанию.
  • Управление командами и организациями — Просматривайте команды, управляйте участниками команд и приглашениями, а также участниками и атрибутами организаций.
  • Поиск в каталоге API — Находите, описывайте и выполняйте любые операции Cal.com API v2 с помощью метаинструментов каталога.

Документация

MCP-сервер

Подключайте ИИ-клиенты к планированию встреч в Cal.com через Model Context Protocol с помощью размещённого сервера на mcp.cal.com или локального экземпляра.

Сервер Cal.com MCP оборачивает Cal.com API v2 в Model Context Protocol, позволяя управлять бронированиями, типами событий, расписаниями и многим другим на естественном языке в любом клиенте, совместимом с MCP.

Размещённый сервер (mcp.cal.com)

Быстрее всего начать — подключить клиент MCP напрямую к mcp.cal.com. Размещённый сервер использует транспорт Streamable HTTP с аутентификацией OAuth 2.1 — клиент автоматически выполняет процесс авторизации.

Подключение клиента

Укажите в клиенте MCP URL размещённого сервера:

https://mcp.cal.com/mcp

При первом подключении клиент проведёт вас через процесс авторизации OAuth, в ходе которого вы предоставите серверу доступ к своей учётной записи Cal.com. API-ключ не требуется. Подключиться может любой клиент MCP: клиенты регистрируются динамически через POST /oauth/register или идентифицируют себя с помощью документа метаданных клиента (URL https client_id). Перед входом в Cal.com вы увидите страницу согласия с названием клиента и хостом, на который вас перенаправят.

[!NOTE]

На экране согласия также запрашиваются области доступа команды, необходимые для создания, редактирования и удаления типов событий команды, а также для просмотра и управления участниками команды. Благодаря этому ИИ-клиент может настраивать типы событий команды и добавлять людей в команды. Также запрашиваются области доступа к профилю организации, чтобы ИИ-клиент администратора организации мог просматривать, создавать, редактировать и удалять команды организации. Cal.com по-прежнему проверяет вашу роль и разрешения в команде при каждом вызове. Кроме того, запрашивается разрешение на просмотр, добавление, переименование и удаление личных контактов (CONTACT_READ, CONTACT_WRITE). Если вы подключились до добавления этих областей доступа, отключите сервер и подключитесь снова, чтобы предоставить их.

[tab] Claude Desktop

Добавьте следующее в 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

Откройте Settings → MCP и добавьте сервер, указав URL https://mcp.cal.com/mcp, или добавьте его в .cursor/mcp.json:

{
  "mcpServers": {
    "calcom": {
      "url": "https://mcp.cal.com/mcp"
    }
  }
}

[tab] VS Code

Добавьте сервер в настройки MCP для VS Code:

{
  "mcpServers": {
    "calcom": {
      "url": "https://mcp.cal.com/mcp"
    }
  }
}

[tab] fx

Добавьте следующее в ~/.fx/mcp.json:

{
  "mcp": {
    "calcom": {
      "type": "http",
      "url": "https://mcp.cal.com/mcp"
    }
  }
}

Затем выполните в fx команду /mcp auth calcom --open, чтобы авторизоваться. Подробнее о транспортах, вариантах аутентификации и обнаружении инструментов см. в документации fx MCP.

[tab] Grok

Grok подключается через бота Cal.com, а не через конфигурацию JSON. В разделе Settings → Developer → MCP выберите Grok Bot в разделе Client setup, затем отсканируйте QR-код или нажмите Add Bot, чтобы открыть бота Cal.com в 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

Локальный сервер (stdio)

Если вы предпочитаете запускать сервер локально, можно использовать транспорт stdio с API-ключом. Это удобно для разработки или если вы хотите полностью контролировать сервер.

Предварительные требования

Подключение клиента

Добавьте следующее в конфигурацию клиента MCP:

{
  "mcpServers": {
    "calcom": {
      "command": "npx",
      "args": ["@calcom/cal-mcp@latest"],
      "env": {
        "CAL_API_KEY": "cal_live_xxxx"
      }
    }
  }
}

Замените cal_live_xxxx своим API-ключом.

[!WARNING]

Никогда не передавайте и не добавляйте в систему контроля версий свой API-ключ. Если он стал доступен посторонним, немедленно смените его в настройках Cal.com.

Запуск HTTP-сервера с помощью Docker Compose

Чтобы разместить сервер Streamable HTTP с OAuth самостоятельно, используйте файл apps/mcp/docker-compose.yml из репозитория Cal.com. Он запускает MCP-сервер и базу данных PostgreSQL за прокси-сервером Caddy на портах 80 и 443.

Перед запуском задайте MCP_POSTGRES_PASSWORD. Compose откажется запускаться без этой переменной. Поскольку пароль также включается в строку подключения сервера к базе данных, используйте только символы, безопасные для URL.

export MCP_POSTGRES_PASSWORD="$(openssl rand -hex 24)"
docker compose -f apps/mcp/docker-compose.yml up -d

PostgreSQL не публикуется на порту хоста. Подключаться к ней может только MCP-сервер через сеть Compose. Чтобы подключиться к базе данных самостоятельно, используйте docker compose -f apps/mcp/docker-compose.yml exec postgres psql -U mcp mcp.

[!NOTE]

PostgreSQL считывает пароль только при первом создании тома данных. Если том был создан с более ранней версией файла Compose, пароль в нём по-прежнему равен mcp. Задайте MCP_POSTGRES_PASSWORD=mcp или смените пароль с помощью ALTER USER mcp PASSWORD '...' и укажите новое значение.

Наборы инструментов

Можно ограничить набор инструментов, регистрируемых сервером для сеанса, добавив к URL сервера параметр запроса toolsets:

https://mcp.cal.com/mcp?toolsets=bookings,availability

Допустимые наборы инструментов: profile, event-types, events, bookings, availability, schedules, calendars, contacts, discover, teams, organizations, routing-forms, catalog (метаинструменты find_api_operation / describe_api_operation / call_api_operation). Неизвестные имена отклоняются с ошибкой 400 invalid_request. Если параметр не указан, регистрируются все инструменты; локальные инструменты get_app_link и search_docs регистрируются всегда, независимо от выбора. Для локального сервера stdio задайте MCP_TOOLSETS.

Интерактивные представления (MCP Apps)

В клиентах с поддержкой MCP Apps инструменты get_availability и get_bookings также отображают в чате интерактивное представление. В нём можно выбирать время и управлять бронированиями щелчками, а не вводом текста:

  • Выбор временного слота (get_availability): доступное время сгруппировано по дням. Используйте стрелки, чтобы перейти к более ранним или поздним датам, выберите время, введите имя и адрес электронной почты участника, затем нажмите Book. Если ассистент подбирает новое время для существующего бронирования, при выборе времени вместо этого появится вариант Move booking here.
  • Бронирования (get_bookings): для каждого бронирования отображается отдельная карточка со временем и участниками. Для предстоящих бронирований доступны действия Join (если у бронирования есть ссылка на встречу), Reschedule (показывает доступное время на следующую неделю) и Cancel (сначала предлагает подтвердить отмену в карточке).

Время отображается в часовом поясе, который сообщает клиент, а оформление представлений соответствует его светлой или тёмной теме. Действия выполняются с помощью тех же инструментов create_booking, reschedule_booking и cancel_booking в существующем подключении, а ассистент получает информацию о выполненном действии.

[!NOTE]

Представления доступны, только если включены оба набора инструментов — bookings и availability. По умолчанию они включены, если не передан параметр toolsets. Клиенты без поддержки MCP Apps получают те же текстовые результаты, что и раньше.

Подписки на события (MCP Events)

Размещённый сервер поддерживает MCP Events, поэтому клиенты, использующие версию протокола 2026-07-28, могут получать уведомления о событиях в вашей учётной записи Cal.com вместо периодических запросов. Сервер объявляет возможность events и обрабатывает три метода:

  • events/list: возвращает список событий, на которые можно подписаться, например booking.created, booking.rescheduled, booking.cancelled, meeting.ended и recording.ready. Для каждого события указаны схема входных данных и схема полезной нагрузки.
  • events/subscribe: подписывает URL обратного вызова на событие. URL должен быть общедоступным адресом HTTPS, а delivery.secret должен быть секретом типа whsec_. Перед сохранением подписки сервер отправляет подписанный запрос проверки с параметром challenge, который ваша конечная точка должна вернуть в ответе JSON. Повторная подписка с теми же URL, событием и аргументами обновляет существующую подписку.
  • events/unsubscribe: удаляет одну из ваших подписок. Вызов метода для уже удалённой подписки завершается успешно.

Уведомления подписываются с помощью Standard Webhooks с использованием секрета whsec_. По умолчанию срок действия подписок истекает через 7 дней; задайте ttlMs, чтобы указать срок от 1 часа до 30 дней.

При создании первой подписки в вашей учётной записи Cal.com создаётся вебхук, который отправляет события на маршрут сервера POST /events/calcom/<ref>. При удалении последней подписки вебхук удаляется. Самостоятельно вызывать этот маршрут не нужно.

[!NOTE]

MCP Events доступны только через транспорт Streamable HTTP, но не через локальный сервер stdio. Они не связаны с набором инструментов events, который управляет страницами RSVP для Cal Events.

Доступные инструменты

Сервер MCP предоставляет 85 инструментов, сгруппированных по категориям:

Ссылки на приложение

ИнструментОписание
get_app_linkСоздать URL, открывающий в веб-приложении Cal.com страницу бронирования, типа события, расписания, команды, формы маршрутизации или настроек

Документация

ИнструментОписание
search_docsИскать в документации продукта Cal.com; возвращает ранжированный список страниц с фрагментом из лучшего результата

Профиль пользователя

ИнструментОписание
get_meПолучить профиль пользователя, прошедшего аутентификацию
update_meОбновить профиль пользователя

Типы событий

ИнструментОписание
get_event_typesПолучить список всех типов событий
get_event_typeПолучить сведения о типе события по его ID
create_event_typeСоздать тип события
update_event_typeОбновить тип события
delete_event_typeУдалить тип события
duplicate_event_typeСкопировать тип события команды организации в ту же команду или другую команду организации
get_event_type_settingsПолучить настройки типа события
get_event_type_historyПолучить историю изменений типа события
get_scheduling_configПолучить конфигурацию планирования типа события
get_crm_sync_errorsПолучить ошибки синхронизации с CRM для типа события

События

Cal Events — это страницы RSVP с фиксированной датой, доступные по адресу cal.com/{slug}, а не типы событий и не события календаря. Для get_events и get_event требуется область OAuth EVENT_READ, а для invite_cal_event_guests — EVENT_WRITE.

ИнструментОписание
get_eventsПолучить список событий, которыми вы владеете или которые проводите совместно, начиная с самых новых; поддерживаются limit (максимум 250), постраничная навигация cursor и фильтр slug
get_eventПолучить сведения об одном событии по uuid
invite_cal_event_guestsОтправить приглашение по электронной почте на каждый указанный адрес, каждому из ваших контактов по ID (contactIds) или всем контактам с одной из ваших меток контактов (contactTagIds); для контактов требуется функция contacts; сообщает результат для каждого адреса

Бронирования

ИнструментОписание
get_bookingsПолучить список бронирований с необязательными фильтрами
get_bookingПолучить сведения о бронировании по UID
create_bookingСоздать бронирование
reschedule_bookingПеренести бронирование
cancel_bookingОтменить бронирование
confirm_bookingПодтвердить ожидающее бронирование
mark_booking_absentОтметить отсутствие на бронировании
get_booking_attendeesПолучить список всех участников бронирования
add_booking_attendeeДобавить участника в бронирование
get_booking_attendeeПолучить сведения об участнике
get_booking_routing_traceПолучить трассировку маршрутизации для бронирования
get_org_team_bookingsПолучить бронирования команды организации
get_org_user_bookingsПолучить бронирования пользователя организации

Расписания

ИнструментОписание
get_schedulesПолучить список всех расписаний
get_scheduleПолучить сведения о расписании по ID
create_scheduleСоздать расписание
update_scheduleОбновить расписание
delete_scheduleУдалить расписание
get_default_scheduleПолучить расписание по умолчанию

Доступность и календари

ИнструментОписание
get_availabilityПолучить доступные временные слоты
get_busy_timesПолучить занятое время из календарей
get_connected_calendarsПолучить список подключённых календарей
get_conferencing_appsПолучить список приложений для видеоконференций

Контакты

Ваши личные контакты и их теги со страницы «Контакты» — не участники команды или организации. Для списков требуется область OAuth CONTACT_READ, а для изменений — CONTACT_WRITE. Теги общие для контактов и ссылок.

ИнструментОписание
list_contactsСписок ваших контактов, по 50 на страницу, при необходимости — только контакты с определёнными тегами; также указано, зарегистрирован ли каждый контакт в Cal и может ли он присоединиться к групповой встрече
add_contactДобавить контакт по адресу электронной почты, при необходимости указав имя
update_contactИзменить имя контакта; имя контакта, зарегистрированного в Cal, изменить нельзя
remove_contactУдалить контакт и его теги
list_contact_tagsСписок ваших тегов, по 50 на страницу, с указанием количества контактов с каждым тегом
create_contact_tagСоздать тег, не назначая его ни одному контакту
add_contact_tagНазначить контактy один тег
remove_contact_tagСнять с контакта один тег; сам тег останется

Discover

Опубликованные объявления Discover, которые можно искать или просматривать по идентификаторам, возвращённым поиском; для этого требуется область OAuth EVENT_TYPE_READ. Звонки компаниям, найденным в интернете, онлайн-бронирование у них и запросы на уведомление о появлении поставщика требуют области PROFILE_WRITE.

ИнструментОписание
search_listingsИскать объявления по категории, произвольному тексту, району, цене, длительности и временному интервалу с доступными слотами; для каждого объявления возвращается ссылка для бронирования. Если в указанном районе ничего не найдено, отображаются компании, найденные там в интернете
get_discover_listingsПросмотреть до 50 объявлений в том виде, в котором они представлены в публичных карточках; при необходимости для каждого объявления указывается ближайший доступный слот в течение следующих 7 дней
call_business_to_bookПоручить Cal позвонить в компанию, которую search_listings нашёл в интернете, чтобы забронировать услугу, после одобрения пользователя; возвращается страница звонка, где можно следить за его ходом
book_onlineПоручить агенту бронирования Cal самостоятельно забронировать услугу на странице бронирования компании, которую search_listings нашёл в интернете, после одобрения пользователя; возвращается страница задания, где пользователь выбирает вариант и подтверждает цену и условия
record_service_requestЗапросить уведомление по электронной почте на адрес вашей учётной записи, когда появится поставщик услуги, для которой в Discover пока нет объявления; повторный запрос о той же потребности в том же регионе в течение 90 дней ничего не меняет

Команды и членство

ИнструментОписание
get_my_teamsПолучить список команд, в которых вы состоите
get_org_teamsПолучить команды организации
create_team_inviteПригласить кого-либо в команду
create_team_membershipСоздать членство в команде
get_team_membershipsПолучить все членства в командах
get_team_membershipПолучить членство в команде
update_team_membershipИзменить членство в команде
delete_team_membershipУдалить членство в команде

Организации

ИнструментОписание
get_org_membershipsПолучить все членства в организациях
create_org_membershipСоздать членство в организации
get_org_membershipПолучить членство в организации
update_org_membershipИзменить членство в организации
delete_org_membershipУдалить членство в организации
get_org_attributesПолучить атрибуты организации
get_org_attributeПолучить атрибут организации
get_attribute_optionsПолучить варианты атрибута
get_user_attributesПолучить атрибуты, назначенные пользователю
assign_attribute_to_userНазначить атрибут пользователю
update_user_attributeИзменить атрибут, назначенный пользователю
unassign_attribute_from_userСнять атрибут с пользователя
get_user_attribute_historyПолучить историю назначений атрибутов пользователю

Формы маршрутизации

ИнструментОписание
calculate_routing_form_slotsРассчитать слоты на основе ответа в форме маршрутизации
get_org_routing_formsПолучить формы маршрутизации организации
get_org_routing_form_responsesПолучить ответы на формы маршрутизации
get_team_routing_formsПолучить формы маршрутизации команды
create_routing_formСоздать форму маршрутизации команды с резервным маршрутом по умолчанию
get_routing_formПолучить вопросы и маршруты формы маршрутизации команды
get_routing_form_historyПолучить историю изменений формы маршрутизации команды, начиная с самых новых: кто, что и когда изменил; поддерживаются limit (максимум 50) и пагинация cursor
edit_routing_form_routesПредварительно просмотреть и применить изменения маршрутов формы маршрутизации команды
edit_routing_form_fieldsПредварительно просмотреть и применить изменения вопросов формы маршрутизации команды

Каталог API

ИнструментОписание
find_api_operationИскать по полному каталогу операций API v2
describe_api_operationПолучить схему входных данных для операции API
call_api_operationВыполнить любую операцию API v2 из каталога

Примеры запросов

После подключения вы можете взаимодействовать с Cal.com на естественном языке:

  • «Какие встречи у меня запланированы на этой неделе?»
  • «Создай тип события на 30 минут под названием „Короткий разговор“»
  • «Отмени мою завтрашнюю встречу с Джоном»
  • «Покажи доступные слоты на следующий понедельник»
  • «Перенеси мою встречу в 14:00 на четверг, на 15:00»
  • «Какие типы событий у меня есть?»

Связанные материалы

Эта документация создана и размещена на Mintlify, платформе документации для разработчиков.