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 机器人。
自托管服务器(stdio)
如果你更愿意在本地运行服务器,可以使用 stdio 传输和 API 密钥。这适用于开发,或需要完全控制服务器的情况。
前提条件
- Node.js >= 18
- Cal.com API 密钥——在 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 设置 中轮换密钥。
工具集
你可以在服务器 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 构建并托管。
