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.
Локальный сервер (stdio)
Если вы предпочитаете запускать сервер локально, можно использовать транспорт stdio с API-ключом. Это удобно для разработки или если вы хотите полностью контролировать сервер.
Предварительные требования
- Node.js >= 18
- API-ключ Cal.com — создайте его в разделе Settings → Developer → API Keys
Подключение клиента
Добавьте следующее в конфигурацию клиента 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»
- «Какие типы событий у меня есть?»
Связанные материалы
- Руководство по ИИ-агентам — создание ИИ-агентов с использованием API Cal.com напрямую
- Справочник API v2 — полная документация по конечным точкам API
Эта документация создана и размещена на Mintlify, платформе документации для разработчиков.
