Back to Details

google-calendar

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Google Calendar

Google Calendar

Interact with Google Calendar for event management, scheduling, and availability checking.
通过Google Calendar进行日程管理、日程规划和空闲状态查询。

Installation

安装

  1. Install Python dependencies:
    bash
    pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml
  2. Download the skill from Releases or use directly from this repository.
  1. 安装Python依赖:
    bash
    pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml
  2. 从Releases下载该工具，或直接使用本仓库中的内容。

Setup Verification

安装验证

After installation, verify the skill is properly configured:
bash
python scripts/google-calendar.py check
This will check:
  • Python dependencies (google-auth, google-auth-oauthlib, google-api-python-client, keyring, pyyaml)
  • Authentication configuration
  • Connectivity to Google Calendar API
If anything is missing, the check command will provide setup instructions.
安装完成后，验证工具是否配置正确：
bash
python scripts/google-calendar.py check
该命令会检查：
  • Python依赖（google-auth、google-auth-oauthlib、google-api-python-client、keyring、pyyaml）
  • 认证配置
  • 与Google Calendar API的连接性
如果有缺失项，检查命令会提供对应的设置说明。

Authentication

认证

Google Calendar uses OAuth 2.0 for authentication. For complete setup instructions, see:
  1. GCP Project Setup Guide - Create project, enable Calendar API
  2. Google OAuth Setup Guide - Configure credentials
Google Calendar使用OAuth 2.0进行认证。完整设置说明请参考：
  1. GCP项目设置指南 - 创建项目，启用Calendar API
  2. Google OAuth设置指南 - 配置凭证

Quick Start

快速开始

  1. Create 
    ~/.config/agent-skills/google.yaml
    :
    yaml
    oauth_client:
  client_id: your-client-id.apps.googleusercontent.com
  client_secret: your-client-secret
  2. Run 
    python scripts/google-calendar.py check
    to trigger OAuth flow and verify setup.
  1. 创建
    ~/.config/agent-skills/google.yaml
    文件：
    yaml
    oauth_client:
  client_id: your-client-id.apps.googleusercontent.com
  client_secret: your-client-secret
  2. 运行
    python scripts/google-calendar.py check
    触发OAuth流程并验证设置。

OAuth Scopes

OAuth权限范围

The skill requests granular scopes for different operations:
ScopePermissionUsed For
calendar.readonly
Read calendars and eventslist, get events
calendar.events
Create/edit/delete eventscreate, update, delete
该工具针对不同操作请求细分的权限范围：
权限范围权限说明适用场景
calendar.readonly
读取日历和日程列出、获取日程
calendar.events
创建/编辑/删除日程创建、更新、删除日程

Scope Errors

权限范围错误

If you encounter "insufficient scope" errors, revoke your token and re-authenticate:
  1. Revoke at https://myaccount.google.com/permissions
  2. Clear token: 
    keyring del agent-skills google-calendar-token-json
  3. Re-run: 
    python scripts/google-calendar.py check
如果遇到「权限不足」错误，请撤销令牌并重新认证：
  1. 在https://myaccount.google.com/permissions撤销权限
  2. 清除令牌：
    keyring del agent-skills google-calendar-token-json
  3. 重新运行：
    python scripts/google-calendar.py check

Commands

命令说明

check

check

Verify configuration and connectivity.
bash
python scripts/google-calendar.py check
This validates:
  • Python dependencies are installed
  • Authentication is configured
  • Can connect to Google Calendar API
  • Displays your primary calendar information
验证配置和连接性。
bash
python scripts/google-calendar.py check
该命令会验证：
  • Python依赖已安装
  • 认证已配置
  • 可连接到Google Calendar API
  • 显示你的主日历信息

auth setup

auth setup

Store OAuth 2.0 client credentials for custom OAuth flow.
bash
python scripts/google-calendar.py auth setup \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET
Credentials are saved to 
~/.config/agent-skills/google-calendar.yaml
.
存储OAuth 2.0客户端凭证以支持自定义OAuth流程。
bash
python scripts/google-calendar.py auth setup \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET
凭证会保存到
~/.config/agent-skills/google-calendar.yaml
。

calendars list

calendars list

List all calendars for the authenticated user.
bash
undefined
列出已认证用户的所有日历。
bash
undefined

List calendars

列出日历

python scripts/google-calendar.py calendars list
python scripts/google-calendar.py calendars list

Output as JSON

以JSON格式输出

python scripts/google-calendar.py calendars list --json

**Arguments:**
- `--json`: Output as JSON
python scripts/google-calendar.py calendars list --json

**参数:**
- `--json`: 以JSON格式输出

calendars get

calendars get

Get details for a specific calendar.
bash
undefined
获取指定日历的详细信息。
bash
undefined

Get primary calendar

获取主日历信息

python scripts/google-calendar.py calendars get primary
python scripts/google-calendar.py calendars get primary

Get specific calendar by ID

通过日历ID获取指定日历

python scripts/google-calendar.py calendars get CALENDAR_ID
python scripts/google-calendar.py calendars get CALENDAR_ID

Output as JSON

以JSON格式输出

python scripts/google-calendar.py calendars get primary --json

**Arguments:**
- `calendar_id`: Calendar ID or "primary" (required)
- `--json`: Output as JSON
python scripts/google-calendar.py calendars get primary --json

**参数:**
- `calendar_id`: 日历ID或"primary"（必填）
- `--json`: 以JSON格式输出

events list

events list

List calendar events.
bash
undefined
列出日历中的日程。
bash
undefined

List upcoming events

列出即将到来的日程

python scripts/google-calendar.py events list
python scripts/google-calendar.py events list

List events in specific time range

列出指定时间范围内的日程

python scripts/google-calendar.py events list
--time-min "2026-01-24T00:00:00Z"
--time-max "2026-01-31T23:59:59Z"
python scripts/google-calendar.py events list
--time-min "2026-01-24T00:00:00Z"
--time-max "2026-01-31T23:59:59Z"

List events from specific calendar

列出指定日历中的日程

python scripts/google-calendar.py events list --calendar CALENDAR_ID
python scripts/google-calendar.py events list --calendar CALENDAR_ID

Search events

搜索日程

python scripts/google-calendar.py events list --query "meeting"
python scripts/google-calendar.py events list --query "meeting"

List with custom max results

自定义最大结果数量

python scripts/google-calendar.py events list --max-results 20
python scripts/google-calendar.py events list --max-results 20

Output as JSON

以JSON格式输出

python scripts/google-calendar.py events list --json

**Arguments:**
- `--calendar`: Calendar ID (default: "primary")
- `--time-min`: Start time (RFC3339 timestamp, e.g., "2026-01-24T00:00:00Z")
- `--time-max`: End time (RFC3339 timestamp)
- `--max-results`: Maximum number of results (default: 10)
- `--query`: Free text search query
- `--json`: Output as JSON

**Time Format Examples:**
- UTC: `2026-01-24T10:00:00Z`
- With timezone: `2026-01-24T10:00:00-05:00` (EST)
- Date only (all-day): `2026-01-24`
python scripts/google-calendar.py events list --json

**参数:**
- `--calendar`: 日历ID（默认："primary"）
- `--time-min`: 开始时间（RFC3339时间戳，例如"2026-01-24T00:00:00Z"）
- `--time-max`: 结束时间（RFC3339时间戳）
- `--max-results`: 最大结果数量（默认：10）
- `--query`: 自由文本搜索关键词
- `--json`: 以JSON格式输出

**时间格式示例:**
- UTC时间: `2026-01-24T10:00:00Z`
- 带时区: `2026-01-24T10:00:00-05:00`（美国东部时间）
- 仅日期（全天日程）: `2026-01-24`

events get

events get

Get details for a specific event.
bash
undefined
获取指定日程的详细信息。
bash
undefined

Get event from primary calendar

获取主日历中的指定日程

python scripts/google-calendar.py events get EVENT_ID
python scripts/google-calendar.py events get EVENT_ID

Get event from specific calendar

获取指定日历中的指定日程

python scripts/google-calendar.py events get EVENT_ID --calendar CALENDAR_ID
python scripts/google-calendar.py events get EVENT_ID --calendar CALENDAR_ID

Output as JSON

以JSON格式输出

python scripts/google-calendar.py events get EVENT_ID --json

**Arguments:**
- `event_id`: Event ID (required)
- `--calendar`: Calendar ID (default: "primary")
- `--json`: Output as JSON
python scripts/google-calendar.py events get EVENT_ID --json

**参数:**
- `event_id`: 日程ID（必填）
- `--calendar`: 日历ID（默认："primary"）
- `--json`: 以JSON格式输出

events create

events create

Create a new calendar event.
bash
undefined
创建新的日历日程。
bash
undefined

Create simple event with time

创建带时间的简单日程

python scripts/google-calendar.py events create
--summary "Team Meeting"
--start "2026-01-24T10:00:00-05:00"
--end "2026-01-24T11:00:00-05:00"
python scripts/google-calendar.py events create
--summary "Team Meeting"
--start "2026-01-24T10:00:00-05:00"
--end "2026-01-24T11:00:00-05:00"

Create all-day event

创建全天日程

python scripts/google-calendar.py events create
--summary "Conference"
--start "2026-01-24"
--end "2026-01-25"
--timezone "America/New_York"
python scripts/google-calendar.py events create
--summary "Conference"
--start "2026-01-24"
--end "2026-01-25"
--timezone "America/New_York"

Create event with details

创建带详细信息的日程

python scripts/google-calendar.py events create
--summary "Project Review"
--start "2026-01-24T14:00:00Z"
--end "2026-01-24T15:00:00Z"
--description "Quarterly project review meeting"
--location "Conference Room A"
--attendees "alice@example.com,bob@example.com"
python scripts/google-calendar.py events create
--summary "Project Review"
--start "2026-01-24T14:00:00Z"
--end "2026-01-24T15:00:00Z"
--description "Quarterly project review meeting"
--location "Conference Room A"
--attendees "alice@example.com,bob@example.com"

Create on specific calendar

在指定日历中创建日程

python scripts/google-calendar.py events create
--calendar CALENDAR_ID
--summary "Event"
--start "2026-01-24T10:00:00Z"
--end "2026-01-24T11:00:00Z"
python scripts/google-calendar.py events create
--calendar CALENDAR_ID
--summary "Event"
--start "2026-01-24T10:00:00Z"
--end "2026-01-24T11:00:00Z"

Output as JSON

以JSON格式输出

python scripts/google-calendar.py events create
--summary "Meeting"
--start "2026-01-24T10:00:00Z"
--end "2026-01-24T11:00:00Z"
--json

**Arguments:**
- `--summary`: Event title (required)
- `--start`: Start time - RFC3339 timestamp or YYYY-MM-DD for all-day (required)
- `--end`: End time - RFC3339 timestamp or YYYY-MM-DD for all-day (required)
- `--calendar`: Calendar ID (default: "primary")
- `--description`: Event description
- `--location`: Event location
- `--attendees`: Comma-separated list of attendee email addresses
- `--timezone`: Timezone for all-day events (e.g., "America/New_York")
- `--json`: Output as JSON
python scripts/google-calendar.py events create
--summary "Meeting"
--start "2026-01-24T10:00:00Z"
--end "2026-01-24T11:00:00Z"
--json

**参数:**
- `--summary`: 日程标题（必填）
- `--start`: 开始时间 - RFC3339时间戳或YYYY-MM-DD格式（全天日程）（必填）
- `--end`: 结束时间 - RFC3339时间戳或YYYY-MM-DD格式（全天日程）（必填）
- `--calendar`: 日历ID（默认："primary"）
- `--description`: 日程描述
- `--location`: 日程地点
- `--attendees`: 参会者邮箱地址，以逗号分隔
- `--timezone`: 全天日程的时区（例如"America/New_York"）
- `--json`: 以JSON格式输出

events update

events update

Update an existing event.
bash
undefined
更新已有的日程。
bash
undefined

Update event summary

更新日程标题

python scripts/google-calendar.py events update EVENT_ID
--summary "Updated Meeting Title"
python scripts/google-calendar.py events update EVENT_ID
--summary "Updated Meeting Title"

Update event time

更新日程时间

python scripts/google-calendar.py events update EVENT_ID
--start "2026-01-24T15:00:00Z"
--end "2026-01-24T16:00:00Z"
python scripts/google-calendar.py events update EVENT_ID
--start "2026-01-24T15:00:00Z"
--end "2026-01-24T16:00:00Z"

Update multiple fields

更新多个字段

python scripts/google-calendar.py events update EVENT_ID
--summary "Project Sync"
--location "Room B"
--description "Updated agenda"
python scripts/google-calendar.py events update EVENT_ID
--summary "Project Sync"
--location "Room B"
--description "Updated agenda"

Update event on specific calendar

更新指定日历中的日程

python scripts/google-calendar.py events update EVENT_ID
--calendar CALENDAR_ID
--summary "New Title"
python scripts/google-calendar.py events update EVENT_ID
--calendar CALENDAR_ID
--summary "New Title"

Output as JSON

以JSON格式输出

python scripts/google-calendar.py events update EVENT_ID
--summary "Meeting"
--json

**Arguments:**
- `event_id`: Event ID (required)
- `--calendar`: Calendar ID (default: "primary")
- `--summary`: New event title
- `--start`: New start time (RFC3339 or YYYY-MM-DD)
- `--end`: New end time (RFC3339 or YYYY-MM-DD)
- `--description`: New description
- `--location`: New location
- `--json`: Output as JSON
python scripts/google-calendar.py events update EVENT_ID
--summary "Meeting"
--json

**参数:**
- `event_id`: 日程ID（必填）
- `--calendar`: 日历ID（默认："primary"）
- `--summary`: 新的日程标题
- `--start`: 新的开始时间（RFC3339或YYYY-MM-DD格式）
- `--end`: 新的结束时间（RFC3339或YYYY-MM-DD格式）
- `--description`: 新的日程描述
- `--location`: 新的日程地点
- `--json`: 以JSON格式输出

events delete

events delete

Delete a calendar event.
bash
undefined
删除日历中的日程。
bash
undefined

Delete event from primary calendar

删除主日历中的日程

python scripts/google-calendar.py events delete EVENT_ID
python scripts/google-calendar.py events delete EVENT_ID

Delete event from specific calendar

删除指定日历中的日程

python scripts/google-calendar.py events delete EVENT_ID --calendar CALENDAR_ID

**Arguments:**
- `event_id`: Event ID (required)
- `--calendar`: Calendar ID (default: "primary")
- `--json`: Output as JSON (for consistency, no output on success)
python scripts/google-calendar.py events delete EVENT_ID --calendar CALENDAR_ID

**参数:**
- `event_id`: 日程ID（必填）
- `--calendar`: 日历ID（默认："primary"）
- `--json`: 以JSON格式输出（成功时无输出，仅为格式统一）

freebusy

freebusy

Check free/busy information for calendars.
bash
undefined
查询日历的空闲/忙碌状态。
bash
undefined

Check availability for primary calendar

查询主日历的空闲状态

python scripts/google-calendar.py freebusy
--start "2026-01-24T00:00:00Z"
--end "2026-01-25T00:00:00Z"
python scripts/google-calendar.py freebusy
--start "2026-01-24T00:00:00Z"
--end "2026-01-25T00:00:00Z"

Check multiple calendars

查询多个日历的空闲状态

python scripts/google-calendar.py freebusy
--start "2026-01-24T08:00:00Z"
--end "2026-01-24T17:00:00Z"
--calendars "primary,calendar1@example.com,calendar2@example.com"
python scripts/google-calendar.py freebusy
--start "2026-01-24T08:00:00Z"
--end "2026-01-24T17:00:00Z"
--calendars "primary,calendar1@example.com,calendar2@example.com"

Output as JSON

以JSON格式输出

python scripts/google-calendar.py freebusy
--start "2026-01-24T00:00:00Z"
--end "2026-01-25T00:00:00Z"
--json

**Arguments:**
- `--start`: Start time (RFC3339 timestamp, required)
- `--end`: End time (RFC3339 timestamp, required)
- `--calendars`: Comma-separated calendar IDs (default: "primary")
- `--json`: Output as JSON
python scripts/google-calendar.py freebusy
--start "2026-01-24T00:00:00Z"
--end "2026-01-25T00:00:00Z"
--json

**参数:**
- `--start`: 开始时间（RFC3339时间戳，必填）
- `--end`: 结束时间（RFC3339时间戳，必填）
- `--calendars`: 日历ID列表，以逗号分隔（默认："primary"）
- `--json`: 以JSON格式输出

Examples

使用示例

Verify Setup

验证安装设置

bash
python scripts/google-calendar.py check
bash
python scripts/google-calendar.py check

View upcoming events

查看即将到来的日程

bash
undefined
bash
undefined

Next 10 events

查看接下来的10个日程

python scripts/google-calendar.py events list
python scripts/google-calendar.py events list

This week's events

查看本周的日程

python scripts/google-calendar.py events list
--time-min "2026-01-24T00:00:00Z"
--time-max "2026-01-31T23:59:59Z"
undefined
python scripts/google-calendar.py events list
--time-min "2026-01-24T00:00:00Z"
--time-max "2026-01-31T23:59:59Z"
undefined

Create a meeting

创建会议日程

bash
python 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 "team@example.com"
bash
python 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 "team@example.com"

Schedule an all-day event

安排全天日程

bash
python scripts/google-calendar.py events create \
  --summary "Company Holiday" \
  --start "2026-12-25" \
  --end "2026-12-26" \
  --timezone "America/New_York"
bash
python scripts/google-calendar.py events create \
  --summary "Company Holiday" \
  --start "2026-12-25" \
  --end "2026-12-26" \
  --timezone "America/New_York"

Reschedule an event

重新安排日程

bash
python scripts/google-calendar.py events update EVENT_ID \
  --start "2026-01-24T14:00:00Z" \
  --end "2026-01-24T15:00:00Z"
bash
python scripts/google-calendar.py events update EVENT_ID \
  --start "2026-01-24T14:00:00Z" \
  --end "2026-01-24T15:00:00Z"

Find available time slots

查询可用时间段

bash
python scripts/google-calendar.py freebusy \
  --start "2026-01-24T08:00:00-05:00" \
  --end "2026-01-24T17:00:00-05:00" \
  --calendars "primary,colleague@example.com"
bash
python scripts/google-calendar.py freebusy \
  --start "2026-01-24T08:00:00-05:00" \
  --end "2026-01-24T17:00:00-05:00" \
  --calendars "primary,colleague@example.com"

Search for events

搜索日程

bash
python scripts/google-calendar.py events list --query "project review"
bash
python scripts/google-calendar.py events list --query "project review"

Cancel an event

取消日程

bash
python scripts/google-calendar.py events delete EVENT_ID
bash
python scripts/google-calendar.py events delete EVENT_ID

Date and Time Format

日期与时间格式

Google Calendar uses RFC3339 format for timestamps. See calendar-timezones.md for detailed timezone handling.
Google Calendar使用RFC3339格式的时间戳。有关时区处理的详细说明，请参考calendar-timezones.md。

Timed Events

定时日程

Use RFC3339 format with timezone:
2026-01-24T10:00:00-05:00  # 10 AM EST
2026-01-24T10:00:00Z       # 10 AM UTC
2026-01-24T10:00:00+01:00  # 10 AM CET
使用带时区的RFC3339格式：
2026-01-24T10:00:00-05:00  # 美国东部时间上午10点
2026-01-24T10:00:00Z       # UTC时间上午10点
2026-01-24T10:00:00+01:00  # 中欧时间上午10点

All-Day Events

全天日程

Use date format (YYYY-MM-DD):
2026-01-24  # All day on January 24, 2026
For all-day events, you can specify a timezone using the 
--timezone
argument.
使用日期格式（YYYY-MM-DD）：
2026-01-24  # 2026年1月24日全天
对于全天日程，你可以使用
--timezone
参数指定时区。

Troubleshooting

故障排除

Check command fails

Check命令执行失败

Run 
python scripts/google-calendar.py check
to diagnose issues. It will provide specific error messages and setup instructions.
运行
python scripts/google-calendar.py check
诊断问题，它会提供具体的错误信息和设置说明。

Authentication failed

认证失败

  1. Verify your OAuth client ID and client secret are correct in 
    ~/.config/agent-skills/google.yaml
  2. Token expired or corrupted - clear and re-authenticate:
    bash
    keyring del agent-skills google-calendar-token-json
python scripts/google-calendar.py check
  1. 验证
    ~/.config/agent-skills/google.yaml
    中的OAuth客户端ID和密钥是否正确
  2. 令牌过期或损坏 - 清除令牌后重新认证：
    bash
    keyring del agent-skills google-calendar-token-json
python scripts/google-calendar.py check

Permission denied

权限被拒绝

Your OAuth token may not have the necessary scopes. Revoke access at https://myaccount.google.com/permissions, clear your token, and re-authenticate.
你的OAuth令牌可能缺少必要的权限范围。在https://myaccount.google.com/permissions撤销权限，清除令牌后重新认证。

Import errors

导入错误

Ensure dependencies are installed:
bash
pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml
确保已安装所有依赖：
bash
pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

Event not found

日程未找到

Verify the event ID and calendar ID are correct. Event IDs are unique per calendar.
验证日程ID和日历ID是否正确。日程ID在每个日历中是唯一的。

Timezone issues

时区问题

Always use RFC3339 format with explicit timezone offsets, or UTC (Z suffix). For all-day events, use YYYY-MM-DD format and optionally specify 
--timezone
.
始终使用带明确时区偏移的RFC3339格式，或UTC时间（带Z后缀）。对于全天日程，使用YYYY-MM-DD格式，并可选择指定
--timezone
参数。

Rate limiting

速率限制

Google Calendar API has quota limits. If you hit rate limits, wait a few minutes before retrying. For high-volume usage, consider requesting quota increases in the Google Cloud Console.
Google Calendar API有配额限制。如果触发速率限制，请等待几分钟后重试。对于高频率使用场景，可考虑在Google Cloud Console中申请提高配额。

API Scopes

API权限范围

This skill requests the following OAuth scopes:
  • https://www.googleapis.com/auth/calendar.readonly
    - Read calendar events and settings
  • https://www.googleapis.com/auth/calendar.events
    - Create, update, and delete events
These scopes provide full calendar management capabilities while following the principle of least privilege.
该工具请求以下OAuth权限范围：
  • https://www.googleapis.com/auth/calendar.readonly
    - 读取日历日程和设置
  • https://www.googleapis.com/auth/calendar.events
    - 创建、更新和删除日程
这些权限范围在遵循最小权限原则的同时，提供了完整的日历管理能力。

Security Notes

安全说明

  • OAuth tokens are stored securely in your system keyring
  • Client secrets are stored in 
    ~/.config/agent-skills/google-calendar.yaml
    with file permissions 600
  • No passwords are stored - only OAuth tokens
  • Tokens refresh automatically when using the skill
  • Browser-based consent ensures you approve all requested permissions
Always review OAuth consent screens before granting access to your Google Calendar.
  • OAuth令牌安全存储在系统密钥环中
  • 客户端密钥存储在
    ~/.config/agent-skills/google-calendar.yaml
    ，文件权限为600
  • 不存储密码 - 仅存储OAuth令牌
  • 令牌会自动刷新 - 使用工具时自动完成
  • 基于浏览器的授权 - 确保你批准所有请求的权限
在授予Google Calendar访问权限前，请务必仔细查看OAuth授权界面。