google-calendar

Google Calendar

轻量级 Google Calendar 集成，使用独立的 OAuth 身份验证。无需 MCP 服务。

⚠️ 需要 Google Workspace 账号。 不支持个人 Gmail 账号。

首次设置

通过 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

列出活动

# List events from primary calendar (default: next 30 days)
python scripts/gcal.py list-events

# List events with specific time range
python scripts/gcal.py list-events --time-min 2024-01-15T00:00:00Z --time-max 2024-01-31T23:59:59Z

# List events from a specific calendar
python scripts/gcal.py list-events --calendar "[email protected]"

# Limit results
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 "[email protected]"

创建活动

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

# Event with description and location
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"

# Event with attendees
python scripts/gcal.py create-event "Team Meeting" "2024-01-15T10:00:00Z" "2024-01-15T11:00:00Z" \
    --attendees [email protected] [email protected]

# Event on specific calendar
python scripts/gcal.py create-event "Meeting" "2024-01-15T10:00:00Z" "2024-01-15T11:00:00Z" \
    --calendar "[email protected]"

更新活动

# Update event title
python scripts/gcal.py update-event EVENT_ID --summary "New Title"

# Update event time
python scripts/gcal.py update-event EVENT_ID --start "2024-01-15T14:00:00Z" --end "2024-01-15T15:00:00Z"

# Update multiple fields
python scripts/gcal.py update-event EVENT_ID \
    --summary "Updated Meeting" --description "New agenda" --location "Room B"

# Update attendees
python scripts/gcal.py update-event EVENT_ID --attendees [email protected] [email protected]

删除活动

python scripts/gcal.py delete-event EVENT_ID
python scripts/gcal.py delete-event EVENT_ID --calendar "[email protected]"

查找空闲时间

查找与指定参会者开会的首个可用时段：

# Find 30-minute slot for yourself
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

# Find 60-minute slot with multiple attendees
python scripts/gcal.py find-free-time \
    --attendees me [email protected] [email protected] \
    --time-min "2024-01-15T09:00:00Z" \
    --time-max "2024-01-19T17:00:00Z" \
    --duration 60

回复活动邀请

# Accept an invitation
python scripts/gcal.py respond-to-event EVENT_ID accepted

# Decline an invitation
python scripts/gcal.py respond-to-event EVENT_ID declined

# Mark as tentative
python scripts/gcal.py respond-to-event EVENT_ID tentative

# Respond without notifying organizer
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 的云函数自动刷新。