Cal.com MCP

官方

通过位于 mcp.cal.com 的托管服务器或本地实例,使用 Model Context Protocol 将 AI 客户端连接到 Cal.com 的日程安排。

你可以用 Cal Com MCP 做什么?

  • 管理预订 — 让助手列出、创建、改期、取消或确认预订,并为预订添加参与者。
  • 查看可用时间 — 获取空闲时段、已连接日历中的忙碌时段,以及默认日程安排。
  • 设置活动类型 — 创建、更新、复制或删除活动类型,包括团队活动类型。
  • 管理日程和联系人 — 创建和编辑日程,并添加、更新或标记个人联系人。
  • 管理团队和组织 — 邀请团队成员、管理成员资格,以及列出或编辑组织团队和属性。
  • 搜索文档和 API 目录 — 搜索 Cal.com 文档,或查找、描述并调用任意 API v2 操作。

文档

MCP 服务器

通过托管服务器 mcp.cal.com 或本地实例,使用模型上下文协议将 AI 客户端连接到 Cal.com 日程安排服务。

Cal.com MCP 服务器通过模型上下文协议封装 Cal.com API v2,让你可以在任何兼容 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 动态注册,或使用 Client ID Metadata Document(一个 https client_id URL)标识自身。在 Cal.com 登录之前,你会看到一个同意页面,其中会显示客户端名称以及授权后将返回的主机。

[!NOTE]

同意页面还会请求团队作用域,以创建、编辑和删除团队活动类型,以及查看和管理团队成员资格,这样 AI 客户端就可以设置团队活动类型并将人员添加到团队中。页面还会请求组织资料作用域,以便组织管理员的 AI 客户端列出、创建、编辑和删除组织的团队。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

将服务器添加到 VS Code MCP 设置中:

{
  "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 中,在 Client setup 下选择 Grok Bot,然后扫描二维码或点击 Add Bot,在 Grok 中打开 Cal.com 机器人。

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 设置 中轮换密钥。

工具集

你可以在服务器 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 订阅到某个事件。回调必须是公开的 HTTPS URL,且 delivery.secret 必须是 whsec_ 密钥。保存订阅之前,服务器会发送一个带签名的验证请求,其中包含 challenge 值;你的端点必须在 JSON 响应中原样返回该值。使用相同的 URL、事件和参数再次订阅会刷新现有订阅。
  • events/unsubscribe:移除一项订阅。即使该订阅已不存在,调用此方法也会成功。

投递内容使用你的 whsec_ 密钥,通过 Standard Webhooks 签名。订阅默认在 7 天后过期;设置 ttlMs 可请求 1 小时至 30 天的有效期。

首次创建订阅时,系统会在你的账户中创建一个 Cal.com webhook,将事件发送到服务器的 POST /events/calcom/<ref> 路由;移除最后一项订阅时则会删除该 webhook。你无需自行调用此路由。

[!NOTE]

MCP Events 仅通过 Streamable HTTP 传输提供,自托管的 stdio 服务器不支持。它与管理 Cal Events RSVP 页面的 events 工具集无关。

可用工具

MCP 服务器提供 85 个工具,按类别组织:

应用链接

工具描述
get_app_link构建一个 URL,用于在 Cal.com Web 应用中打开预订、活动类型、日程安排、团队、路由表单或设置页面

文档

工具描述
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 是在 cal.com/{slug} 提供的固定日期 RSVP 页面——既不是活动类型,也不是日历事件。get_events 和 get_event 需要 EVENT_READ OAuth 作用域,invite_cal_event_guests 则需要 EVENT_WRITE。

工具描述
get_events按时间从新到旧列出你拥有或共同主持的 Events;支持 limit(最多 250 条)和 cursor 分页,以及 slug 筛选条件
get_event按 uuid 获取一个 Event
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列出会议应用

联系人

你的个人联系人及其标签来自“联系人”页面——不包括团队或组织成员。列出联系人需要 CONTACT_READ OAuth 作用域,写入操作需要 CONTACT_WRITE。标签会与你的链接共享。

工具描述
list_contacts列出你的联系人,每页 50 个;可选仅显示带有指定标签的联系人,并显示每位联系人是否使用 Cal 以及能否加入群组会议
add_contact通过电子邮件添加联系人,可选填写姓名
update_contact更新联系人的姓名;使用 Cal 的联系人无法更改姓名
remove_contact移除联系人及其标签
list_contact_tags列出你的标签,每页 50 个,并显示每个标签关联的联系人数量
create_contact_tag创建标签,但不将其添加到任何联系人
add_contact_tag为联系人添加一个标签
remove_contact_tag从联系人移除一个标签;标签本身会保留

发现

已发布的 Discover 列表,可通过搜索返回的 ID 进行搜索或读取,需要 EVENT_TYPE_READ OAuth 作用域;在网上找到的商家可供致电和在线预约,也可请求在服务提供商加入时通知你,这些操作需要 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 分钟活动类型”
  • “取消我明天与 John 的会议”
  • “显示我下周一的可用时段”
  • “将我下午 2 点的会议改到周四下午 3 点”
  • “我有哪些活动类型?”

相关资源

本文档使用开发者文档平台 Mintlify 构建并托管。