Google Calendar

Interact with Google Calendar for event management, scheduling, and availability checking.

通过Google Calendar进行日程管理、日程规划和空闲状态查询。

Installation

安装

Install Python dependencies:

bash

pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

Download the skill from Releases or use directly from this repository.

安装Python依赖:

bash

pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

从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:

GCP Project Setup Guide - Create project, enable Calendar API
Google OAuth Setup Guide - Configure credentials

Google Calendar使用OAuth 2.0进行认证。完整设置说明请参考：

GCP项目设置指南 - 创建项目，启用Calendar API
Google OAuth设置指南 - 配置凭证

Quick Start

快速开始

Create

~/.config/agent-skills/google.yaml

:

yaml

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

Run
```
python scripts/google-calendar.py check
```
to trigger OAuth flow and verify setup.

创建

~/.config/agent-skills/google.yaml

文件：

yaml

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

运行
```
python scripts/google-calendar.py check
```
触发OAuth流程并验证设置。

OAuth Scopes

OAuth权限范围

The skill requests granular scopes for different operations:

Scope	Permission	Used For
`calendar.readonly`	Read calendars and events	list, get events
`calendar.events`	Create/edit/delete events	create, update, delete

该工具针对不同操作请求细分的权限范围：

权限范围	权限说明	适用场景
`calendar.readonly`	读取日历和日程	列出、获取日程
`calendar.events`	创建/编辑/删除日程	创建、更新、删除日程

Scope Errors

权限范围错误

If you encounter "insufficient scope" errors, revoke your token and re-authenticate:

Revoke at https://myaccount.google.com/permissions

Clear token:

keyring del agent-skills google-calendar-token-json

Re-run:
```
python scripts/google-calendar.py check
```

如果遇到「权限不足」错误，请撤销令牌并重新认证：

在https://myaccount.google.com/permissions撤销权限

清除令牌：

keyring del agent-skills google-calendar-token-json

重新运行：
```
python scripts/google-calendar.py check
```

Commands

命令说明

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

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

List all calendars for the authenticated user.

bash

undefined

列出已认证用户的所有日历。

bash

undefined

List calendars

列出日历

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

Get details for a specific calendar.

bash

undefined

获取指定日历的详细信息。

bash

undefined

Get primary calendar

获取主日历信息

python scripts/google-calendar.py calendars get primary

Get specific calendar by ID

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

List calendar events.

bash

undefined

列出日历中的日程。

bash

undefined

List upcoming events

列出即将到来的日程

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"

List events from specific calendar

列出指定日历中的日程

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

Search events

搜索日程

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

List with custom max results

自定义最大结果数量

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

Get details for a specific event.

bash

undefined

获取指定日程的详细信息。

bash

undefined

Get event from primary calendar

获取主日历中的指定日程

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

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

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"

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"

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"

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"

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

Update an existing event.

bash

undefined

更新已有的日程。

bash

undefined

Update event summary

更新日程标题

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"

Update multiple fields

更新多个字段

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"

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

Delete a calendar event.

bash

undefined

删除日历中的日程。

bash

undefined

Delete event from primary calendar

删除主日历中的日程

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

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"

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"

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

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

认证失败

Verify your OAuth client ID and client secret are correct in
```
~/.config/agent-skills/google.yaml
```

Token expired or corrupted - clear and re-authenticate:

bash

keyring del agent-skills google-calendar-token-json
python scripts/google-calendar.py check

验证
```
~/.config/agent-skills/google.yaml
```
中的OAuth客户端ID和密钥是否正确

令牌过期或损坏 - 清除令牌后重新认证：

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授权界面。

google-calendar

Original

Translation

Google Calendar

Google Calendar

Installation

安装

Setup Verification

安装验证

Authentication

认证

Quick Start

快速开始

OAuth Scopes

OAuth权限范围

Scope Errors

权限范围错误

Commands

命令说明

check

check

auth setup

auth setup

calendars list

calendars list

List calendars

列出日历

Output as JSON

以JSON格式输出

calendars get

calendars get

Get primary calendar

获取主日历信息

Get specific calendar by ID

通过日历ID获取指定日历

Output as JSON

以JSON格式输出

events list

events list

List upcoming events

列出即将到来的日程

List events in specific time range

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

List events from specific calendar

列出指定日历中的日程

Search events

搜索日程

List with custom max results

自定义最大结果数量

Output as JSON

以JSON格式输出

events get

events get

Get event from primary calendar

获取主日历中的指定日程

Get event from specific calendar

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

Output as JSON

以JSON格式输出

events create

events create

Create simple event with time

创建带时间的简单日程

Create all-day event

创建全天日程

Create event with details

创建带详细信息的日程

Create on specific calendar

在指定日历中创建日程

Output as JSON

以JSON格式输出

events update

events update

Update event summary

更新日程标题

Update event time

更新日程时间

Update multiple fields

更新多个字段

Update event on specific calendar