Back to Details

cal-com-automation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cal.com Automation via Rube MCP

通过Rube MCP实现Cal.com自动化

Automate Cal.com scheduling operations through Composio's Cal toolkit via Rube MCP.
通过Composio的Cal工具包，借助Rube MCP自动化Cal.com的日程安排操作。

Prerequisites

前提条件

  • Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
  • Active Cal.com connection via 
    RUBE_MANAGE_CONNECTIONS
    with toolkit 
    cal
  • Always call 
    RUBE_SEARCH_TOOLS
    first to get current tool schemas
  • 必须已连接Rube MCP（需可使用RUBE_SEARCH_TOOLS）
  • 通过
    RUBE_MANAGE_CONNECTIONS
    并使用工具包
    cal
    建立有效的Cal.com连接
  • 请始终先调用
    RUBE_SEARCH_TOOLS
    以获取最新的工具架构

Setup

设置步骤

Get Rube MCP: Add 
https://rube.app/mcp
as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
  1. Verify Rube MCP is available by confirming 
    RUBE_SEARCH_TOOLS
    responds
  2. Call 
    RUBE_MANAGE_CONNECTIONS
    with toolkit 
    cal
  3. If connection is not ACTIVE, follow the returned auth link to complete Cal.com authentication
  4. Confirm connection status shows ACTIVE before running any workflows
获取Rube MCP：在客户端配置中添加
https://rube.app/mcp
作为MCP服务器。无需API密钥——只需添加该端点即可使用。
  1. 通过确认
    RUBE_SEARCH_TOOLS
    能正常响应，验证Rube MCP是否可用
  2. 调用
    RUBE_MANAGE_CONNECTIONS
    并指定工具包
    cal
  3. 如果连接状态未激活，请按照返回的授权链接完成Cal.com身份验证
  4. 在运行任何工作流之前，确认连接状态显示为ACTIVE

Core Workflows

核心工作流

1. Manage Bookings

1. 管理预订

When to use: User wants to list, create, or review bookings
Tool sequence:
  1. CAL_FETCH_ALL_BOOKINGS
    - List all bookings with filters [Required]
  2. CAL_POST_NEW_BOOKING_REQUEST
    - Create a new booking [Optional]
Key parameters for listing:
  • status
    : Filter by booking status ('upcoming', 'recurring', 'past', 'cancelled', 'unconfirmed')
  • afterStart
    : Filter bookings after this date (ISO 8601)
  • beforeEnd
    : Filter bookings before this date (ISO 8601)
Key parameters for creation:
  • eventTypeId
    : Event type ID for the booking
  • start
    : Booking start time (ISO 8601)
  • end
    : Booking end time (ISO 8601)
  • name
    : Attendee name
  • email
    : Attendee email
  • timeZone
    : Attendee timezone (IANA format)
  • language
    : Attendee language code
  • metadata
    : Additional metadata object
Pitfalls:
  • Date filters use ISO 8601 format with timezone (e.g., '2024-01-15T09:00:00Z')
  • eventTypeId
    must reference a valid, active event type
  • Booking creation requires matching an available slot; check availability first
  • Time zone must be a valid IANA timezone string (e.g., 'America/New_York')
  • Status filter values are specific strings; invalid values return empty results
适用场景：用户需要列出、创建或查看预订
工具执行序列:
  1. CAL_FETCH_ALL_BOOKINGS
    - 按筛选条件列出所有预订 [必填]
  2. CAL_POST_NEW_BOOKING_REQUEST
    - 创建新预订 [可选]
列出预订的关键参数:
  • status
    : 按预订状态筛选（'upcoming'、'recurring'、'past'、'cancelled'、'unconfirmed'）
  • afterStart
    : 筛选此日期之后的预订（ISO 8601格式）
  • beforeEnd
    : 筛选此日期之前的预订（ISO 8601格式）
创建预订的关键参数:
  • eventTypeId
    : 预订对应的活动类型ID
  • start
    : 预订开始时间（ISO 8601格式）
  • end
    : 预订结束时间（ISO 8601格式）
  • name
    : 参会人姓名
  • email
    : 参会人邮箱
  • timeZone
    : 参会人时区（IANA格式）
  • language
    : 参会人语言代码
  • metadata
    : 附加元数据对象
注意事项:
  • 日期筛选器需使用带时区的ISO 8601格式（例如：'2024-01-15T09:00:00Z'）
  • eventTypeId
    必须指向有效的、已激活的活动类型
  • 创建预订前需先检查可用时段，确保所选时段有空余
  • 时区必须是有效的IANA时区字符串（例如：'America/New_York'）
  • 状态筛选值为特定字符串，无效值将返回空结果

2. Check Availability

2. 检查可用时段

When to use: User wants to find free/busy times or available booking slots
Tool sequence:
  1. CAL_RETRIEVE_CALENDAR_BUSY_TIMES
    - Get busy time blocks [Required]
  2. CAL_GET_AVAILABLE_SLOTS_INFO
    - Get specific available slots [Required]
Key parameters:
  • dateFrom
    : Start date for availability check (YYYY-MM-DD)
  • dateTo
    : End date for availability check (YYYY-MM-DD)
  • eventTypeId
    : Event type to check slots for
  • timeZone
    : Timezone for the availability response
  • loggedInUsersTz
    : Timezone of the requesting user
Pitfalls:
  • Busy times show when the user is NOT available
  • Available slots are specific to an event type's duration and configuration
  • Date range should be reasonable (not months in advance) to get accurate results
  • Timezone affects how slots are displayed; always specify explicitly
  • Availability reflects calendar integrations (Google Calendar, Outlook, etc.)
适用场景：用户需要查找空闲/忙碌时段或可预订的时段
工具执行序列:
  1. CAL_RETRIEVE_CALENDAR_BUSY_TIMES
    - 获取忙碌时段块 [必填]
  2. CAL_GET_AVAILABLE_SLOTS_INFO
    - 获取具体的可用时段 [必填]
关键参数:
  • dateFrom
    : 可用时段检查的开始日期（YYYY-MM-DD格式）
  • dateTo
    : 可用时段检查的结束日期（YYYY-MM-DD格式）
  • eventTypeId
    : 要检查时段的活动类型
  • timeZone
    : 可用时段响应的时区
  • loggedInUsersTz
    : 请求用户的时区
注意事项:
  • 忙碌时段表示用户不可用的时间
  • 可用时段特定于活动类型的时长和配置
  • 日期范围应合理（不要提前数月）以获取准确结果
  • 时区会影响时段的显示方式，请始终明确指定
  • 可用状态会同步日历集成（如Google Calendar、Outlook等）的信息

3. Configure Webhooks

3. 配置Webhook

When to use: User wants to set up or manage webhook notifications for booking events
Tool sequence:
  1. CAL_RETRIEVE_WEBHOOKS_LIST
    - List existing webhooks [Required]
  2. CAL_GET_WEBHOOK_BY_ID
    - Get specific webhook details [Optional]
  3. CAL_UPDATE_WEBHOOK_BY_ID
    - Update webhook configuration [Optional]
  4. CAL_DELETE_WEBHOOK_BY_ID
    - Remove a webhook [Optional]
Key parameters:
  • id
    : Webhook ID for GET/UPDATE/DELETE operations
  • subscriberUrl
    : Webhook endpoint URL
  • eventTriggers
    : Array of event types to trigger on
  • active
    : Whether the webhook is active
  • secret
    : Webhook signing secret
Pitfalls:
  • Webhook URLs must be publicly accessible HTTPS endpoints
  • Event triggers include: 'BOOKING_CREATED', 'BOOKING_RESCHEDULED', 'BOOKING_CANCELLED', etc.
  • Inactive webhooks do not fire; toggle 
    active
    to enable/disable
  • Webhook secrets are used for payload signature verification
适用场景：用户需要设置或管理预订事件的Webhook通知
工具执行序列:
  1. CAL_RETRIEVE_WEBHOOKS_LIST
    - 列出已有的Webhook [必填]
  2. CAL_GET_WEBHOOK_BY_ID
    - 获取特定Webhook的详细信息 [可选]
  3. CAL_UPDATE_WEBHOOK_BY_ID
    - 更新Webhook配置 [可选]
  4. CAL_DELETE_WEBHOOK_BY_ID
    - 删除Webhook [可选]
关键参数:
  • id
    : 用于GET/UPDATE/DELETE操作的Webhook ID
  • subscriberUrl
    : Webhook端点URL
  • eventTriggers
    : 触发Webhook的事件类型数组
  • active
    : Webhook是否处于激活状态
  • secret
    : Webhook签名密钥
注意事项:
  • Webhook URL必须是可公开访问的HTTPS端点
  • 事件触发类型包括：'BOOKING_CREATED'、'BOOKING_RESCHEDULED'、'BOOKING_CANCELLED'等
  • 未激活的Webhook不会触发，可通过切换
    active
    字段启用/禁用
  • Webhook密钥用于验证负载签名

4. Manage Teams

4. 管理团队

When to use: User wants to create, view, or manage teams and team event types
Tool sequence:
  1. CAL_GET_TEAMS_LIST
    - List all teams [Required]
  2. CAL_GET_TEAM_INFORMATION_BY_TEAM_ID
    - Get specific team details [Optional]
  3. CAL_CREATE_TEAM_IN_ORGANIZATION
    - Create a new team [Optional]
  4. CAL_RETRIEVE_TEAM_EVENT_TYPES
    - List event types for a team [Optional]
Key parameters:
  • teamId
    : Team identifier
  • name
    : Team name (for creation)
  • slug
    : URL-friendly team identifier
Pitfalls:
  • Team creation may require organization-level permissions
  • Team event types are separate from personal event types
  • Team slugs must be URL-safe and unique within the organization
适用场景：用户需要创建、查看或管理团队及团队活动类型
工具执行序列:
  1. CAL_GET_TEAMS_LIST
    - 列出所有团队 [必填]
  2. CAL_GET_TEAM_INFORMATION_BY_TEAM_ID
    - 获取特定团队的详细信息 [可选]
  3. CAL_CREATE_TEAM_IN_ORGANIZATION
    - 创建新团队 [可选]
  4. CAL_RETRIEVE_TEAM_EVENT_TYPES
    - 列出团队的活动类型 [可选]
关键参数:
  • teamId
    : 团队标识符
  • name
    : 团队名称（创建时使用）
  • slug
    : 适合URL的团队标识符
注意事项:
  • 创建团队可能需要组织级权限
  • 团队活动类型与个人活动类型相互独立
  • 团队slug必须符合URL安全要求，且在组织内唯一

5. Organization Management

5. 组织管理

When to use: User wants to view organization details
Tool sequence:
  1. CAL_GET_ORGANIZATION_ID
    - Get the organization ID [Required]
Key parameters: (none required)
Pitfalls:
  • Organization ID is needed for team creation and org-level operations
  • Not all Cal.com accounts have organizations; personal plans may return errors
适用场景：用户需要查看组织详细信息
工具执行序列:
  1. CAL_GET_ORGANIZATION_ID
    - 获取组织ID [必填]
关键参数：（无必填参数）
注意事项:
  • 组织ID是创建团队和执行组织级操作的必要条件
  • 并非所有Cal.com账户都有组织，个人计划可能返回错误

Common Patterns

常见模式

Booking Creation Flow

预订创建流程

1. Call CAL_GET_AVAILABLE_SLOTS_INFO to find open slots
2. Present available times to the user
3. Call CAL_POST_NEW_BOOKING_REQUEST with selected slot
4. Confirm booking creation response
1. 调用CAL_GET_AVAILABLE_SLOTS_INFO查找可用时段
2. 向用户展示可用时间
3. 使用所选时段调用CAL_POST_NEW_BOOKING_REQUEST
4. 确认预订创建响应

ID Resolution

ID解析

Team name -> Team ID:
1. Call CAL_GET_TEAMS_LIST
2. Find team by name in response
3. Extract id field
团队名称 -> 团队ID:
1. 调用CAL_GET_TEAMS_LIST
2. 在响应中按名称查找团队
3. 提取id字段

Webhook Setup

Webhook设置

1. Call CAL_RETRIEVE_WEBHOOKS_LIST to check existing hooks
2. Create or update webhook with desired triggers
3. Verify webhook fires on test booking
1. 调用CAL_RETRIEVE_WEBHOOKS_LIST检查已有的Webhook
2. 创建或更新带有所需触发条件的Webhook
3. 测试预订以验证Webhook是否触发

Known Pitfalls

已知注意事项

Date/Time Formats:
  • Booking times: ISO 8601 with timezone (e.g., '2024-01-15T09:00:00Z')
  • Availability dates: YYYY-MM-DD format
  • Always specify timezone explicitly to avoid confusion
Event Types:
  • Event type IDs are numeric integers
  • Event types define duration, location, and booking rules
  • Disabled event types cannot accept new bookings
Permissions:
  • Team operations require team membership or admin access
  • Organization operations require org-level permissions
  • Webhook management requires appropriate access level
Rate Limits:
  • Cal.com API has rate limits per API key
  • Implement backoff on 429 responses
日期/时间格式:
  • 预订时间：带时区的ISO 8601格式（例如：'2024-01-15T09:00:00Z'）
  • 可用时段日期：YYYY-MM-DD格式
  • 请始终明确指定时区以避免混淆
活动类型:
  • 活动类型ID为数字整数
  • 活动类型定义了时长、地点和预订规则
  • 已禁用的活动类型无法接受新预订
权限:
  • 团队操作需要团队成员身份或管理员权限
  • 组织操作需要组织级权限
  • Webhook管理需要相应的访问级别
速率限制:
  • Cal.com API对每个API密钥有速率限制
  • 收到429响应时请实现退避机制

Quick Reference

快速参考

TaskTool SlugKey Params
List bookingsCAL_FETCH_ALL_BOOKINGSstatus, afterStart, beforeEnd
Create bookingCAL_POST_NEW_BOOKING_REQUESTeventTypeId, start, end, name, email
Get busy timesCAL_RETRIEVE_CALENDAR_BUSY_TIMESdateFrom, dateTo
Get available slotsCAL_GET_AVAILABLE_SLOTS_INFOeventTypeId, dateFrom, dateTo
List webhooksCAL_RETRIEVE_WEBHOOKS_LIST(none)
Get webhookCAL_GET_WEBHOOK_BY_IDid
Update webhookCAL_UPDATE_WEBHOOK_BY_IDid, subscriberUrl, eventTriggers
Delete webhookCAL_DELETE_WEBHOOK_BY_IDid
List teamsCAL_GET_TEAMS_LIST(none)
Get teamCAL_GET_TEAM_INFORMATION_BY_TEAM_IDteamId
Create teamCAL_CREATE_TEAM_IN_ORGANIZATIONname, slug
Team event typesCAL_RETRIEVE_TEAM_EVENT_TYPESteamId
Get org IDCAL_GET_ORGANIZATION_ID(none)
任务工具标识关键参数
列出预订CAL_FETCH_ALL_BOOKINGSstatus, afterStart, beforeEnd
创建预订CAL_POST_NEW_BOOKING_REQUESTeventTypeId, start, end, name, email
获取忙碌时段CAL_RETRIEVE_CALENDAR_BUSY_TIMESdateFrom, dateTo
获取可用时段CAL_GET_AVAILABLE_SLOTS_INFOeventTypeId, dateFrom, dateTo
列出WebhookCAL_RETRIEVE_WEBHOOKS_LIST（无）
获取WebhookCAL_GET_WEBHOOK_BY_IDid
更新WebhookCAL_UPDATE_WEBHOOK_BY_IDid, subscriberUrl, eventTriggers
删除WebhookCAL_DELETE_WEBHOOK_BY_IDid
列出团队CAL_GET_TEAMS_LIST（无）
获取团队信息CAL_GET_TEAM_INFORMATION_BY_TEAM_IDteamId
创建团队CAL_CREATE_TEAM_IN_ORGANIZATIONname, slug
团队活动类型CAL_RETRIEVE_TEAM_EVENT_TYPESteamId
获取组织IDCAL_GET_ORGANIZATION_ID（无）