google-calendar

Google Calendar 是一个轻量级的 Google 日历集成技能，采用独立的 OAuth 认证方式，无需 MCP 服务器。它适用于需要与 Google 日历交互的场景，例如检查日历、安排会议、管理事件等。

主要能力

该技能提供以下操作：

列出日历：查看账户下的所有日历。
列出事件：获取指定时间范围内的事件，可指定日历、限制结果数量。
获取事件详情：根据事件 ID 查看具体信息。
创建事件：支持设置标题、开始/结束时间、描述、地点、参与人，并可指定日历。
更新事件：可修改标题、时间、描述、地点、参与人等字段。
删除事件：根据事件 ID 删除事件，可指定日历。
查找空闲时间：为指定参与人查找第一个可用的会议时间段，可设置时间范围和时长。
响应事件邀请：接受、拒绝或暂定参加邀请，可选择是否通知组织者。

使用方式

首次设置

使用前需进行 Google 认证（会打开浏览器）：

python scripts/auth.py login

检查认证状态：

python scripts/auth.py status

登出：

python scripts/auth.py logout

命令操作

所有操作通过 scripts/gcal.py 执行。如果未登录，首次使用时会自动认证。

列出日历

python scripts/gcal.py list-calendars

列出事件

# 列出主日历的事件（默认：未来 30 天）
python scripts/gcal.py list-events

# 指定时间范围
python scripts/gcal.py list-events --time-min 2024-01-15T00:00:00Z --time-max 2024-01-31T23:59:59Z

# 指定日历
python scripts/gcal.py list-events --calendar "work@example.com"

# 限制结果数量
python scripts/gcal.py list-events --max-results 10

获取事件详情

python scripts/gcal.py get-event EVENT_ID
python scripts/gcal.py get-event EVENT_ID --calendar "work@example.com"

创建事件

# 基本事件
python scripts/gcal.py create-event "Team Meeting" "2024-01-15T10:00:00Z" "2024-01-15T11:00:00Z"

# 带描述和地点
python scripts/gcal.py create-event "Team Meeting" "2024-01-15T10:00:00Z" "2024-01-15T11:00:00Z" \
    --description "Weekly sync" --location "Conference Room A"

# 带参与人
python scripts/gcal.py create-event "Team Meeting" "2024-01-15T10:00:00Z" "2024-01-15T11:00:00Z" \
    --attendees user1@example.com user2@example.com

# 指定日历
python scripts/gcal.py create-event "Meeting" "2024-01-15T10:00:00Z" "2024-01-15T11:00:00Z" \
    --calendar "work@example.com"

更新事件

# 更新标题
python scripts/gcal.py update-event EVENT_ID --summary "New Title"

# 更新时间
python scripts/gcal.py update-event EVENT_ID --start "2024-01-15T14:00:00Z" --end "2024-01-15T15:00:00Z"

# 更新多个字段
python scripts/gcal.py update-event EVENT_ID \
    --summary "Updated Meeting" --description "New agenda" --location "Room B"

# 更新参与人
python scripts/gcal.py update-event EVENT_ID --attendees user1@example.com user3@example.com

删除事件

python scripts/gcal.py delete-event EVENT_ID
python scripts/gcal.py delete-event EVENT_ID --calendar "work@example.com"

查找空闲时间

# 为自己查找 30 分钟空闲时段
python scripts/gcal.py find-free-time \
    --attendees me \
    --time-min "2024-01-15T09:00:00Z" \
    --time-max "2024-01-15T17:00:00Z" \
    --duration 30

# 为多个参与人查找 60 分钟空闲时段
python scripts/gcal.py find-free-time \
    --attendees me user1@example.com user2@example.com \
    --time-min "2024-01-15T09:00:00Z" \
    --time-max "2024-01-19T17:00:00Z" \
    --duration 60

响应事件邀请

# 接受邀请
python scripts/gcal.py respond-to-event EVENT_ID accepted

# 拒绝邀请
python scripts/gcal.py respond-to-event EVENT_ID declined

# 暂定参加
python scripts/gcal.py respond-to-event EVENT_ID tentative

# 响应但不通知组织者
python scripts/gcal.py respond-to-event EVENT_ID accepted --no-notify

日期/时间格式

所有时间使用 ISO 8601 格式并带时区：

UTC：2024-01-15T10:30:00Z
带偏移：2024-01-15T10:30:00-05:00（EST）

日历 ID 格式

主日历：使用 primary 或省略 --calendar 参数。
其他日历：使用 list-calendars 返回的日历 ID（通常是电子邮件地址）。

令牌管理

令牌通过系统密钥环安全存储：

macOS：Keychain
Windows：Windows Credential Locker
Linux：Secret Service API（GNOME Keyring、KDE Wallet 等）

服务名称：google-calendar-skill-oauth

令牌过期时会通过 Google 的云函数自动刷新。

适用场景

需要以编程方式管理 Google 日历事件的自动化流程。
在 AI 技能或脚本中集成日历查询、创建、更新、删除等操作。
为会议安排查找共同空闲时间。

限制

需要 Google Workspace 账户，不支持个人 Gmail 账户。
依赖 Python 环境运行脚本。
首次使用需通过浏览器完成 OAuth 认证。