mcpField
G
google-calendar

google-calendar

github.com/odyssey4me生产力131.2k 次安装今天更新
代码仓库

关于 google-calendar

供 Agent 使用的 Google Calendar 技能，可通过 Python 脚本和 OAuth 认证管理日程、安排会议并查询空闲时间。

主要功能

  1. 01创建和查看日历活动
  2. 02查询多个日历的空闲时间
  3. 03管理日历认证
  4. 04处理分页活动结果

适用场景

  1. 01安排带参会者的会议
  2. 02查找多人共同空闲时间
  3. 03查看指定日期范围内的活动

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/odyssey4me/agent-skills --skill google-calendar

安装后在 Claude Code 中输入/google-calendar确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
calendar-timezones.md
command-reference.md
permissions.md
scripts/
google-calendar.py

详细介绍

Google Calendar

通过 Google Calendar 管理日程、安排活动并检查可用时间。

安装

依赖项：pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

验证设置

安装后，验证技能是否已正确配置：

$SKILL_DIR/scripts/google-calendar.py check

此操作会检查：

  • Python 依赖项（google-auth、google-auth-oauthlib、google-api-python-client、keyring、pyyaml）
  • 身份验证配置
  • 与 Google Calendar API 的连通性

如果缺少任何内容，检查命令会提供设置说明。

身份验证

Google Calendar 使用 OAuth 2.0 进行身份验证。完整设置说明请参阅：

  1. GCP 项目设置指南 - 创建项目并启用 Calendar API
  2. Google OAuth 设置指南 - 配置凭据
快速开始

  1. 创建 ~/.config/agent-skills/google.yaml：

    oauth_client:
  client_id: your-client-id.apps.googleusercontent.com
  client_secret: your-client-secret

  2. 运行 $SKILL_DIR/scripts/google-calendar.py check 以触发 OAuth 流程并验证设置。

如果出现作用域或身份验证错误，请参阅 OAuth 故障排除指南。

脚本用法

每条命令的读写分类请参阅 permissions.md。

# Setup and auth
$SKILL_DIR/scripts/google-calendar.py check
$SKILL_DIR/scripts/google-calendar.py auth setup --client-id ID --client-secret SECRET
$SKILL_DIR/scripts/google-calendar.py auth reset
$SKILL_DIR/scripts/google-calendar.py auth status

# Calendars
$SKILL_DIR/scripts/google-calendar.py calendars list
$SKILL_DIR/scripts/google-calendar.py calendars get CALENDAR_ID

# Events
$SKILL_DIR/scripts/google-calendar.py events list
$SKILL_DIR/scripts/google-calendar.py events get EVENT_ID
$SKILL_DIR/scripts/google-calendar.py events create --summary TITLE --start TIME --end TIME
$SKILL_DIR/scripts/google-calendar.py events update EVENT_ID --summary TITLE
$SKILL_DIR/scripts/google-calendar.py events delete EVENT_ID

# Availability
$SKILL_DIR/scripts/google-calendar.py freebusy --start TIME --end TIME

所有命令均支持 --calendar CALENDAR_ID（默认值为 "primary"）。时间使用 RFC3339 格式（例如 2026-01-24T10:00:00Z），全天活动则使用 YYYY-MM-DD。

完整的参数详情和示例请参阅 command-reference.md。

示例

安排包含参会者的会议
$SKILL_DIR/scripts/google-calendar.py events create \
  --summary "Team Standup" \
  --start "2026-01-25T09:00:00-05:00" \
  --end "2026-01-25T09:30:00-05:00" \
  --location "Zoom" \
  --attendees "[email protected]"
查找多个日历中的可用时间
$SKILL_DIR/scripts/google-calendar.py freebusy \
  --start "2026-01-24T08:00:00-05:00" \
  --end "2026-01-24T17:00:00-05:00" \
  --calendars "primary,[email protected]"
列出本周的活动
$SKILL_DIR/scripts/google-calendar.py events list \
  --time-min "2026-01-24T00:00:00Z" \
  --time-max "2026-01-31T23:59:59Z"

Agent 指南 — 分页

活动列表会自动分页，获取所有结果。指定时间范围时，无论数量多少，都会返回所有匹配的活动，不会静默截断结果。

Agent 指南 — 已拒绝的活动

列出活动时，默认会排除已拒绝的会议。脚本输出会说明是否筛除了已拒绝的邀请（例如：“未显示 3 个已拒绝的邀请”）。出现此提示时，请告知用户存在已拒绝的邀请，并询问是否需要显示。若要包含已拒绝的活动，请使用 --include-declined 重新运行。

错误处理

身份验证和作用域错误不可重试。 如果命令因身份验证错误、作用域不足错误或权限被拒绝错误（退出代码为 1）而失败，请停止并告知用户。不要重试或尝试自行修复问题——这些错误需要用户参与（通过浏览器进行 OAuth 授权）。请指引用户查看 OAuth 故障排除指南。

可重试错误：速率限制（HTTP 429）和临时服务器错误（HTTP 5xx）在短暂等待后重试可能会成功。其他所有错误都应报告给用户。

模型指南

此技能会调用 API，要求输入和输出均采用结构化格式。建议使用标准能力的模型。

故障排除

未找到活动

确认活动 ID 和日历 ID 正确无误。活动 ID 在每个日历中都是唯一的。

时区问题

始终使用带有明确时区偏移的 RFC3339 格式，或使用 UTC（Z 后缀）。对于全天活动，请使用 YYYY-MM-DD 格式，并可选择指定 --timezone。

评论

支持 Markdown