google-calendar-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Calendar Automation via Rube MCP

通过Rube MCP实现Google Calendar自动化

Automate Google Calendar workflows including event creation, scheduling, availability checks, attendee management, and calendar browsing through Composio's Google Calendar toolkit.

通过Composio的Google Calendar工具包自动化日历工作流，包括事件创建、日程安排、空闲时间查询、参会人管理以及日历浏览。

Prerequisites

前提条件

Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
Active Google Calendar connection via
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
googlecalendar
```
Always call
```
RUBE_SEARCH_TOOLS
```
first to get current tool schemas

已连接Rube MCP（可使用RUBE_SEARCH_TOOLS）
通过
```
RUBE_MANAGE_CONNECTIONS
```
建立了与
```
googlecalendar
```
工具包的有效Google Calendar连接
请始终先调用
```
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.

Verify Rube MCP is available by confirming
```
RUBE_SEARCH_TOOLS
```
responds
Call
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
googlecalendar
```
If connection is not ACTIVE, follow the returned auth link to complete Google OAuth
Confirm connection status shows ACTIVE before running any workflows

获取Rube MCP: 在客户端配置中添加

https://rube.app/mcp

作为MCP服务器。无需API密钥——只需添加该端点即可使用。

确认
```
RUBE_SEARCH_TOOLS
```
可正常响应，以此验证Rube MCP可用
调用
```
RUBE_MANAGE_CONNECTIONS
```
并指定工具包为
```
googlecalendar
```
如果连接未处于活跃状态，请按照返回的授权链接完成Google OAuth验证
在运行任何工作流之前，确认连接状态显示为活跃

Core Workflows

核心工作流

1. Create and Manage Events

1. 创建与管理事件

When to use: User wants to create, update, or delete calendar events

Tool sequence:

```
GOOGLECALENDAR_LIST_CALENDARS
```
- Identify target calendar ID [Prerequisite]
```
GOOGLECALENDAR_GET_CURRENT_DATE_TIME
```
- Get current time with proper timezone [Optional]
```
GOOGLECALENDAR_FIND_FREE_SLOTS
```
- Check availability before booking [Optional]
```
GOOGLECALENDAR_CREATE_EVENT
```
- Create the event [Required]
```
GOOGLECALENDAR_PATCH_EVENT
```
- Update specific fields of an existing event [Alternative]
```
GOOGLECALENDAR_UPDATE_EVENT
```
- Full replacement update of an event [Alternative]
```
GOOGLECALENDAR_DELETE_EVENT
```
- Delete an event [Optional]

Key parameters:

```
calendar_id
```
: Use 'primary' for main calendar, or specific calendar ID
```
start_datetime
```
: ISO 8601 format 'YYYY-MM-DDTHH:MM:SS' (NOT natural language)
```
timezone
```
: IANA timezone name (e.g., 'America/New_York', NOT 'EST' or 'PST')
```
event_duration_hour
```
: Hours (0+)
```
event_duration_minutes
```
: Minutes (0-59 only; NEVER use 60+)
```
summary
```
: Event title
```
attendees
```
: Array of email addresses (NOT names)
```
location
```
: Free-form text for event location

Pitfalls:

```
start_datetime
```
must be ISO 8601; natural language like 'tomorrow' is rejected

event_duration_minutes

max is 59; use

event_duration_hour=1

instead of

event_duration_minutes=60

```
timezone
```
must be IANA identifier; abbreviations like 'EST', 'PST' are NOT valid
```
attendees
```
only accepts email addresses, not names; resolve names first
Google Meet link creation defaults to true; may fail on personal Gmail accounts (graceful fallback)
Organizer is auto-added as attendee unless
```
exclude_organizer=true
```

适用场景: 用户需要创建、更新或删除日历事件

工具序列:

```
GOOGLECALENDAR_LIST_CALENDARS
```
- 确定目标日历ID [前提步骤]
```
GOOGLECALENDAR_GET_CURRENT_DATE_TIME
```
- 获取带有时区的当前时间 [可选]
```
GOOGLECALENDAR_FIND_FREE_SLOTS
```
- 预订前查询空闲时间 [可选]
```
GOOGLECALENDAR_CREATE_EVENT
```
- 创建事件 [必需]
```
GOOGLECALENDAR_PATCH_EVENT
```
- 更新现有事件的特定字段 [替代方案]
```
GOOGLECALENDAR_UPDATE_EVENT
```
- 完全替换更新事件内容 [替代方案]
```
GOOGLECALENDAR_DELETE_EVENT
```
- 删除事件 [可选]

关键参数:

```
calendar_id
```
: 主日历使用'primary'，或指定具体的日历ID
```
start_datetime
```
: ISO 8601格式（如'YYYY-MM-DDTHH:MM:SS'），不接受自然语言
```
timezone
```
: IANA时区名称（例如'America/New_York'，不接受'EST'或'PST'这类缩写）
```
event_duration_hour
```
: 时长（小时，0及以上）
```
event_duration_minutes
```
: 时长（分钟，仅0-59；请勿使用60及以上的值）
```
summary
```
: 事件标题
```
attendees
```
: 邮箱地址数组（不接受姓名）
```
location
```
: 事件地点的自由文本描述

注意事项:

```
start_datetime
```
必须为ISO 8601格式；'明天'这类自然语言会被拒绝

event_duration_minutes

最大值为59；如需1小时，请使用

event_duration_hour=1

而非

event_duration_minutes=60

```
timezone
```
必须为IANA标识符；'EST'、'PST'这类缩写无效
```
attendees
```
仅接受邮箱地址，不接受姓名；请先解析姓名对应的邮箱
Google Meet链接创建默认开启，在个人Gmail账户上可能失败（需优雅降级处理）
组织者会自动被添加为参会人，除非设置
```
exclude_organizer=true
```

2. List and Search Events

2. 列出与搜索事件

When to use: User wants to find or browse events on their calendar

Tool sequence:

```
GOOGLECALENDAR_LIST_CALENDARS
```
- Get available calendars [Prerequisite]
```
GOOGLECALENDAR_FIND_EVENT
```
- Search by title/keyword with time bounds [Required]
```
GOOGLECALENDAR_EVENTS_LIST
```
- List events in a time range [Alternative]
```
GOOGLECALENDAR_EVENTS_INSTANCES
```
- List instances of a recurring event [Optional]

Key parameters:

```
query
```
/
```
q
```
: Free-text search (matches summary, description, location, attendees)
```
timeMin
```
: Lower bound (RFC3339 with timezone offset, e.g., '2024-01-01T00:00:00-08:00')
```
timeMax
```
: Upper bound (RFC3339 with timezone offset)
```
singleEvents
```
: true to expand recurring events into instances
```
orderBy
```
: 'startTime' (requires singleEvents=true) or 'updated'
```
maxResults
```
: Results per page (max 2500)

Pitfalls:

Timezone warning: UTC timestamps (ending in 'Z') don't align with local dates; use local timezone offsets instead
Example: '2026-01-19T00:00:00Z' covers 2026-01-18 4pm to 2026-01-19 4pm in PST
Omitting
```
timeMin
```
/
```
timeMax
```
scans the full calendar and can be slow
```
pageToken
```
in response means more results; paginate until absent
```
orderBy='startTime'
```
requires
```
singleEvents=true
```

适用场景: 用户需要查找或浏览日历上的事件

工具序列:

```
GOOGLECALENDAR_LIST_CALENDARS
```
- 获取可用日历列表 [前提步骤]
```
GOOGLECALENDAR_FIND_EVENT
```
- 按标题/关键词结合时间范围搜索事件 [必需]
```
GOOGLECALENDAR_EVENTS_LIST
```
- 列出指定时间范围内的事件 [替代方案]
```
GOOGLECALENDAR_EVENTS_INSTANCES
```
- 列出重复事件的所有实例 [可选]

关键参数:

```
query
```
/
```
q
```
: 自由文本搜索（匹配事件标题、描述、地点、参会人）
```
timeMin
```
: 时间范围下限（带时区偏移的RFC3339格式，例如'2024-01-01T00:00:00-08:00'）
```
timeMax
```
: 时间范围上限（带时区偏移的RFC3339格式）
```
singleEvents
```
: 设置为true可将重复事件展开为单独实例
```
orderBy
```
: 排序方式，可选'startTime'（需设置singleEvents=true）或'updated'
```
maxResults
```
: 每页返回的结果数量（最大2500）

注意事项:

时区警告: 以'Z'结尾的UTC时间戳与本地日期不匹配；请使用带本地时区偏移的时间戳
示例: '2026-01-19T00:00:00Z'对应PST时区的2026-01-18 16:00到2026-01-19 16:00
若省略
```
timeMin
```
/
```
timeMax
```
，会扫描整个日历，可能导致响应缓慢
响应中的
```
pageToken
```
表示还有更多结果；需循环调用直到该字段不存在
使用
```
orderBy='startTime'
```
时必须设置
```
singleEvents=true
```

3. Manage Attendees and Invitations

3. 管理参会人与邀请

When to use: User wants to add, remove, or update event attendees

Tool sequence:

GOOGLECALENDAR_FIND_EVENT

GOOGLECALENDAR_EVENTS_LIST

- Find the event [Prerequisite]

```
GOOGLECALENDAR_PATCH_EVENT
```
- Add attendees (replaces entire attendees list) [Required]
```
GOOGLECALENDAR_REMOVE_ATTENDEE
```
- Remove a specific attendee by email [Required]

Key parameters:

```
event_id
```
: Unique event identifier (opaque string, NOT the event title)
```
attendees
```
: Full list of attendee emails (PATCH replaces entire list)
```
attendee_email
```
: Email to remove
```
send_updates
```
: 'all', 'externalOnly', or 'none'

Pitfalls:

```
event_id
```
is a technical identifier, NOT the event title; always search first to get the ID
```
PATCH_EVENT
```
attendees field replaces the entire list; include existing attendees to avoid removing them
Attendee names cannot be resolved; always use email addresses
Use
```
GMAIL_SEARCH_PEOPLE
```
to resolve names to emails before managing attendees

适用场景: 用户需要添加、移除或更新事件参会人

工具序列:

GOOGLECALENDAR_FIND_EVENT

或

GOOGLECALENDAR_EVENTS_LIST

- 查找目标事件 [前提步骤]

```
GOOGLECALENDAR_PATCH_EVENT
```
- 添加参会人（会替换整个参会人列表） [必需]
```
GOOGLECALENDAR_REMOVE_ATTENDEE
```
- 通过邮箱移除特定参会人 [必需]

关键参数:

```
event_id
```
: 事件唯一标识符（随机字符串，并非事件标题）
```
attendees
```
: 完整的参会人邮箱列表（PATCH操作会替换整个列表）
```
attendee_email
```
: 要移除的参会人邮箱
```
send_updates
```
: 发送更新的范围，可选'all'、'externalOnly'或'none'

注意事项:

```
event_id
```
是技术标识符，并非事件标题；请务必先搜索获取该ID
```
PATCH_EVENT
```
的参会人字段会替换整个列表；若要保留现有参会人，需将其包含在新列表中
无法解析参会人姓名；请始终使用邮箱地址
可使用
```
GMAIL_SEARCH_PEOPLE
```
将姓名解析为邮箱后再管理参会人

4. Check Availability and Free/Busy Status

4. 查询空闲/忙碌状态与可用时段

When to use: User wants to find available time slots or check busy periods

Tool sequence:

```
GOOGLECALENDAR_LIST_CALENDARS
```
- Identify calendars to check [Prerequisite]
```
GOOGLECALENDAR_GET_CURRENT_DATE_TIME
```
- Get current time with timezone [Optional]
```
GOOGLECALENDAR_FIND_FREE_SLOTS
```
- Find free intervals across calendars [Required]
```
GOOGLECALENDAR_FREE_BUSY_QUERY
```
- Get raw busy periods for computing gaps [Fallback]
```
GOOGLECALENDAR_CREATE_EVENT
```
- Book a confirmed slot [Required]

Key parameters:

```
items
```
: List of calendar IDs to check (e.g., ['primary'])
```
time_min
```
/
```
time_max
```
: Query interval (defaults to current day if omitted)
```
timezone
```
: IANA timezone for interpreting naive timestamps
```
calendarExpansionMax
```
: Max calendars (1-50)
```
groupExpansionMax
```
: Max members per group (1-100)

Pitfalls:

Maximum span ~90 days per Google Calendar freeBusy API limit
Very long ranges or inaccessible calendars yield empty/invalid results
Only calendars with at least freeBusyReader access are visible
Free slots responses may normalize to UTC ('Z'); check offsets
```
GOOGLECALENDAR_FREE_BUSY_QUERY
```
requires RFC3339 timestamps with timezone

适用场景: 用户需要查找可用时段或查询忙碌时段

工具序列:

```
GOOGLECALENDAR_LIST_CALENDARS
```
- 确定要查询的日历 [前提步骤]
```
GOOGLECALENDAR_GET_CURRENT_DATE_TIME
```
- 获取带有时区的当前时间 [可选]
```
GOOGLECALENDAR_FIND_FREE_SLOTS
```
- 跨日历查找空闲时段 [必需]
```
GOOGLECALENDAR_FREE_BUSY_QUERY
```
- 获取原始忙碌时段数据以计算空闲间隙 [备选方案]
```
GOOGLECALENDAR_CREATE_EVENT
```
- 预订确认后的空闲时段 [必需]

关键参数:

```
items
```
: 要查询的日历ID列表（例如['primary']）
```
time_min
```
/
```
time_max
```
: 查询时间范围（若省略则默认查询当天）
```
timezone
```
: 用于解析无时区时间戳的IANA时区
```
calendarExpansionMax
```
: 最多查询的日历数量（1-50）
```
groupExpansionMax
```
: 每个群组最多查询的成员数量（1-100）

注意事项:

Google Calendar freeBusy API的单次查询最大时间跨度约为90天
过长的时间范围或无法访问的日历会返回空或无效结果
仅能查询具有freeBusyReader权限的日历
空闲时段响应可能会被标准化为UTC时间（以'Z'结尾）；请检查时区偏移
```
GOOGLECALENDAR_FREE_BUSY_QUERY
```
要求使用带时区的RFC3339时间戳

Common Patterns

常见模式

ID Resolution

ID解析

Calendar name -> calendar_id:
```
GOOGLECALENDAR_LIST_CALENDARS
```
to enumerate all calendars

Event title -> event_id:

GOOGLECALENDAR_FIND_EVENT

GOOGLECALENDAR_EVENTS_LIST

Attendee name -> email:
```
GMAIL_SEARCH_PEOPLE
```

日历名称 -> calendar_id: 使用
```
GOOGLECALENDAR_LIST_CALENDARS
```
枚举所有日历

事件标题 -> event_id: 使用

GOOGLECALENDAR_FIND_EVENT

或

GOOGLECALENDAR_EVENTS_LIST

查询

参会人姓名 -> 邮箱: 使用
```
GMAIL_SEARCH_PEOPLE
```
解析

Timezone Handling

时区处理

Always use IANA timezone identifiers (e.g., 'America/Los_Angeles')
Use
```
GOOGLECALENDAR_GET_CURRENT_DATE_TIME
```
to get current time in user's timezone
When querying events for a local date, use timestamps with local offset, NOT UTC
Example: '2026-01-19T00:00:00-08:00' for PST, NOT '2026-01-19T00:00:00Z'

请始终使用IANA时区标识符（例如'America/Los_Angeles'）
使用
```
GOOGLECALENDAR_GET_CURRENT_DATE_TIME
```
获取用户时区的当前时间
查询本地日期的事件时，请使用带本地时区偏移的时间戳，而非UTC时间戳
示例: 对于PST时区，使用'2026-01-19T00:00:00-08:00'而非'2026-01-19T00:00:00Z'

Pagination

分页处理

```
GOOGLECALENDAR_EVENTS_LIST
```
returns
```
nextPageToken
```
; iterate until absent
```
GOOGLECALENDAR_LIST_CALENDARS
```
also paginates; use
```
page_token
```

```
GOOGLECALENDAR_EVENTS_LIST
```
会返回
```
nextPageToken
```
；需循环调用直到该字段不存在
```
GOOGLECALENDAR_LIST_CALENDARS
```
同样支持分页；请使用
```
page_token
```
参数

Known Pitfalls

已知注意事项

Natural language dates: NOT supported; all dates must be ISO 8601 or RFC3339
Timezone mismatch: UTC timestamps don't align with local dates for filtering
Duration limits:
```
event_duration_minutes
```
max 59; use hours for longer durations
IANA timezones only: 'EST', 'PST', etc. are NOT valid; use 'America/New_York'
Event IDs are opaque: Always search to get event_id; never guess or construct
Attendees as emails: Names cannot be used; resolve with GMAIL_SEARCH_PEOPLE
PATCH replaces attendees: Include all desired attendees in the array, not just new ones
Conference limitations: Google Meet may fail on personal accounts (graceful fallback)
Rate limits: High-volume searches can trigger 403/429; throttle between calls

自然语言日期: 不支持；所有日期必须为ISO 8601或RFC3339格式
时区不匹配: UTC时间戳与本地日期过滤不兼容
时长限制:
```
event_duration_minutes
```
最大值为59；更长时长请使用小时参数
仅支持IANA时区: 'EST'、'PST'等缩写无效；请使用'America/New_York'这类标识符
Event ID为随机字符串: 请务必通过查询获取event_id；切勿猜测或自行构造
参会人需用邮箱: 不支持姓名；请使用GMAIL_SEARCH_PEOPLE解析为邮箱
PATCH操作会替换参会人列表: 请在数组中包含所有需要保留的参会人，而非仅新增的
会议链接限制: Google Meet在个人账户上可能无法创建（需优雅降级）
速率限制: 高频率搜索可能触发403/429错误；请在调用之间添加节流

Quick Reference

快速参考

Task	Tool Slug	Key Params
List calendars	`GOOGLECALENDAR_LIST_CALENDARS`	`max_results`
Create event	`GOOGLECALENDAR_CREATE_EVENT`	`start_datetime` , `timezone` , `summary`
Update event	`GOOGLECALENDAR_PATCH_EVENT`	`calendar_id` , `event_id` , fields to update
Delete event	`GOOGLECALENDAR_DELETE_EVENT`	`calendar_id` , `event_id`
Search events	`GOOGLECALENDAR_FIND_EVENT`	`query` , `timeMin` , `timeMax`
List events	`GOOGLECALENDAR_EVENTS_LIST`	`calendarId` , `timeMin` , `timeMax`
Recurring instances	`GOOGLECALENDAR_EVENTS_INSTANCES`	`calendarId` , `eventId`
Find free slots	`GOOGLECALENDAR_FIND_FREE_SLOTS`	`items` , `time_min` , `time_max` , `timezone`
Free/busy query	`GOOGLECALENDAR_FREE_BUSY_QUERY`	`timeMin` , `timeMax` , `items`
Remove attendee	`GOOGLECALENDAR_REMOVE_ATTENDEE`	`event_id` , `attendee_email`
Get current time	`GOOGLECALENDAR_GET_CURRENT_DATE_TIME`	`timezone`
Get calendar	`GOOGLECALENDAR_GET_CALENDAR`	`calendar_id`

任务	工具标识	关键参数
列出日历	`GOOGLECALENDAR_LIST_CALENDARS`	`max_results`
创建事件	`GOOGLECALENDAR_CREATE_EVENT`	`start_datetime` , `timezone` , `summary`
更新事件	`GOOGLECALENDAR_PATCH_EVENT`	`calendar_id` , `event_id` , 待更新字段
删除事件	`GOOGLECALENDAR_DELETE_EVENT`	`calendar_id` , `event_id`
搜索事件	`GOOGLECALENDAR_FIND_EVENT`	`query` , `timeMin` , `timeMax`
列出事件	`GOOGLECALENDAR_EVENTS_LIST`	`calendarId` , `timeMin` , `timeMax`
重复事件实例	`GOOGLECALENDAR_EVENTS_INSTANCES`	`calendarId` , `eventId`
查找空闲时段	`GOOGLECALENDAR_FIND_FREE_SLOTS`	`items` , `time_min` , `time_max` , `timezone`
空闲/忙碌查询	`GOOGLECALENDAR_FREE_BUSY_QUERY`	`timeMin` , `timeMax` , `items`
移除参会人	`GOOGLECALENDAR_REMOVE_ATTENDEE`	`event_id` , `attendee_email`
获取当前时间	`GOOGLECALENDAR_GET_CURRENT_DATE_TIME`	`timezone`
获取日历信息	`GOOGLECALENDAR_GET_CALENDAR`	`calendar_id`