MCP Tools Reference: calendarmcp.googleapis.com

工具：list_events

傳回指定日曆中符合所有指定限制的活動。除非使用者要求，否則請勿指定時間限制。如果要在主要日曆中搜尋開放式關鍵字或主題，則必須改用 search_events 工具。

下列範例示範如何使用 curl 叫用 list_events MCP 工具。

Curl 要求 
curl --location 'https://calendarmcp.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "list_events",
    "arguments": {
      // provide these details according to the tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

輸入內容的結構定義

ListEventsRequest

JSON 表示法 
{
  "eventTypeFilter": [
    string
  ],
  "eventType": [
    enum (EventType)
  ],

  "calendarId": string

  "pageSize": integer

  "pageToken": string

  "startTime": string

  "endTime": string

  "timeZone": string

  "orderBy": string

  "fullText": string
}
欄位
eventTypeFilter[]
(deprecated)

string

(選用步驟) 已淘汰：請改用 event_type。
eventType[]

enum (EventType)

(選用步驟) 要傳回的事件類型。如果為空白，則只會傳回下列事件類型：DEFAULT、OUT_OF_OFFICE、FOCUS_TIME、FROM_GMAIL

聯集欄位 _calendar_id。

_calendar_id 只能是下列其中一項：
calendarId

string

(選用步驟) 包含活動的日曆 ID。電子郵件地址 - 可使用 list_calendars 解析。預設值：主要日曆。

聯集欄位 _page_size。

_page_size 只能是下列其中一項：
pageSize

integer

(選用步驟) 每頁最多活動數 (預設 100，最多 250)。建議：10。

聯集欄位 _page_token。

_page_token 只能是下列其中一項：
pageToken

string

(選用步驟) 下一頁符記。使用上一頁 nextPageToken 中的值。

聯集欄位 _start_time。

_start_time 只能是下列其中一項：
startTime

string

(選用步驟) 時間範圍的下限。只有在使用者要求特定時間範圍時，才必須設定這項屬性。必須是小於 end_time 的 ISO 8601 時間戳記。

聯集欄位 _end_time。

_end_time 只能是下列其中一項：
endTime

string

(選用步驟) 時間範圍的上限。只有在使用者要求特定時間範圍或過去的時間時，才必須設定。必須是 ISO 8601 時間戳記，且大於 start_time。

聯集欄位 _time_zone。

_time_zone 只能是下列其中一項：
timeZone

string

(選用步驟) 用於解析無時區日期的時區 (IANA ID，例如 Europe/Zurich)。預設值：日曆時區。

聯集欄位 _order_by。

_order_by 只能是下列其中一項：
orderBy

string

(選用步驟) 傳回事件的順序。可能的值為：

  • default - 未指定，但排序方式為確定性 (預設)。
  • startTime - Order by start time ascending.
  • startTimeDesc - Order by start time descending.
  • lastModified - Order by last modification time ascending.

聯集欄位 _full_text。

_full_text 只能是下列其中一項：
fullText

string

(選用步驟) 不區分大小寫的自由格式搜尋，可比對標題、說明、地點或與會者。比對包含所有查詢字詞的活動 (AND 搜尋)。

EventType

事件類型。建立後即無法變更。

列舉
EVENT_TYPE_UNSPECIFIED 視為 DEFAULT。
DEFAULT 定期活動。預設值。
OUT_OF_OFFICE 不在辦公室的活動。
FOCUS_TIME 專注時間活動。
WORKING_LOCATION 工作地點活動。
BIRTHDAY 每年舉辦的全天特別活動。
FROM_GMAIL Gmail 中的活動。無法建立這類活動。

輸出內容的結構定義

ListEventsResponse

JSON 表示法 
{
  "summary": string,
  "description": string,
  "updated": string,
  "timeZone": string,
  "accessRole": string,
  "defaultReminders": [
    {
      object (Reminder)
    }
  ],
  "events": [
    {
      object (Event)
    }
  ],

  "nextPageToken": string
}
欄位
summary

string

日曆的名稱。
description

string

日曆說明。
updated

string

日曆的上次更新時間 (ISO 8601)。
timeZone

string

日曆的時區。
accessRole

string

僅供輸出。使用者在日曆中的存取角色。可能的值為：

  • none - 無存取權。
  • freeBusyReader - 讀取有空/忙碌資訊的權限。
  • reader - 日曆的讀取權限。私人活動會顯示，但活動詳細資料不會顯示。
  • writer - 讀取及寫入權限。系統會顯示私人活動，並提供活動詳細資料。
  • owner - 管理員存取權，包括修改日曆共用設定的權限。
重要事項：owner角色與日曆資料擁有者不同。日曆只有一位資料擁有者，但可以有多位具有 owner 角色的使用者。
defaultReminders[]

object (Reminder)

日曆活動的預設提醒。
events[]

object (Event)

事件清單。

聯集欄位 _next_page_token。

_next_page_token 只能是下列其中一項：
nextPageToken

string

下一頁符記。如果沒有下一頁，則省略這個欄位。

提醒

JSON 表示法 
{

  "method": string

  "minutes": integer
}
欄位

聯集欄位 _method。

_method 只能是下列其中一項：
method

string

必填。放送方式。可能的值為：

  • email - 系統會透過電子郵件傳送提醒。
  • popup - 系統會透過 UI 彈出式視窗傳送提醒。

聯集欄位 _minutes。

_minutes 只能是下列其中一項：
minutes

integer

必填。提醒觸發時間提前幾分鐘。

事件

JSON 表示法 
{
  "id": string,
  "status": string,
  "htmlLink": string,
  "created": string,
  "updated": string,
  "summary": string,
  "description": string,
  "location": string,
  "creator": {
    object (Principal)
  },
  "organizer": {
    object (Principal)
  },
  "start": {
    object (DateOrDateTime)
  },
  "end": {
    object (DateOrDateTime)
  },
  "recurrence": [
    string
  ],
  "recurringEventId": string,
  "originalStartTime": {
    object (DateOrDateTime)
  },
  "transparency": string,
  "visibility": string,
  "attendees": [
    {
      object (Attendee)
    }
  ],
  "conferenceUrl": string,
  "colorId": string,
  "overrideReminders": [
    {
      object (Reminder)
    }
  ],
  "attachments": [
    {
      object (Attachment)
    }
  ],
  "guestPermissions": {
    object (GuestPermissions)
  },
  "eventType": enum (EventType),
  "workingLocationProperties": {
    object (WorkingLocationProperties)
  },
  "availability": enum (Availability)
}
欄位
id

string

專屬 ID。
status

string

(選用步驟) 狀態，可能的值為：

  • confirmed - 活動已確認 (預設)。
  • tentative - 活動已暫時確認。
  • cancelled - 活動已取消或刪除。
htmlLink

string

僅供輸出。Google 日曆網頁版使用者介面中，這個活動的絕對連結。
created

string

僅供輸出。建立時間 (ISO 8601)。
updated

string

僅供輸出。上次修改時間 (ISO 8601)。
summary

string

標題。
description

string

(選用步驟) 說明。可包含 HTML。
location

string

(選用步驟) 。
creator

object (Principal)

僅供輸出。創作者。
organizer

object (Principal)

僅供輸出。主辦人。如果出席活動，也會列在與會者名單中。
start

object (DateOrDateTime)

開始時間 (含)。如果是週期性活動，系統會使用第一個執行個體。
end

object (DateOrDateTime)

結束時間 (不含)。如果是週期性活動，系統會使用第一個例項。
recurrence[]

string

重複規則，格式為 RRULE、EXRULE、RDATE 或 EXDATE 字串 (依據 RFC 5545)。如果是單一事件，則會省略這項資訊。開始/結束時間必須在 start/end 欄位中設定。
recurringEventId

string

週期性活動例項的父項週期性活動 ID。
originalStartTime

object (DateOrDateTime)

週期性執行個體的原始開始時間。這是根據週期性資料，這個執行個體應開始的時間。
transparency
(deprecated)

string

(選用步驟) 已淘汰：請改用 availability。
visibility

string

(選用步驟) 活動的顯示設定。可能的值為：

  • default - 使用日曆中活動的預設顯示設定。這是預設值。
  • public - 日曆的所有讀者都能查看活動詳細資料。
  • private - 只有活動出席者可以查看活動詳細資料。
attendees[]

object (Attendee)

與會者。
conferenceUrl

string

視訊會議連結。
colorId

string

活動的顏色。只會影響你的日曆檢視畫面。這是指日曆調色盤中的項目 ID (字串 '1'-'11')：

  • 1：薰衣草色
  • 2：鼠尾草綠
  • 3：葡萄紫
  • 4：紅鶴
  • 5：香蕉
  • 6：橙橘色
  • 7：孔雀藍
  • 8：石墨色
  • 9：藍莓
  • 10：羅勒
  • 11：Tomato。
overrideReminders[]

object (Reminder)

提醒。如未設定，系統會恢復為日曆預設值。
attachments[]

object (Attachment)

檔案附件。
guestPermissions

object (GuestPermissions)

邀請對象權限。
eventType

enum (EventType)

這是指活動類型。
workingLocationProperties

object (WorkingLocationProperties)

工作地點屬性。只有在 event_type 為 WORKING_LOCATION 時才會填入資料。
availability

enum (Availability)

(選用步驟) 線上狀態設定。

主體

JSON 表示法 
{
  "email": string,
  "displayName": string,
  "self": boolean
}
欄位
email

string

電子郵件、
displayName

string

名稱。
self

boolean

僅供輸出。這個主體是否對應於顯示這個活動副本的日曆。預設：false。

DateOrDateTime

JSON 表示法 
{
  "date": string,
  "dateTime": string,
  "timeZone": string
}
欄位
date

string

UTC 午夜的 ISO 8601 日期 (例如 '2019-11-20T00:00:00Z')。
dateTime

string

ISO 8601 時間戳記 (例如 '2019-11-20T08:19:06-07:00')。
timeZone

string

TZDB 時區名稱。

參與者

JSON 表示法 
{

  "id": string

  "email": string

  "displayName": string

  "organizer": boolean

  "self": boolean

  "resource": boolean

  "optionalAttendee": boolean

  "responseStatus": string

  "comment": string

  "additionalGuests": integer
}
欄位

聯集欄位 _id。

_id 只能是下列其中一項：
id

string

僅供輸出。商家檔案 ID。

聯集欄位 _email。

_email 只能是下列其中一項：
email

string

必填。出席者的電子郵件地址。

聯集欄位 _display_name。

_display_name 只能是下列其中一項：
displayName

string

(選用步驟) 名稱。

聯集欄位 _organizer。

_organizer 只能是下列其中一項：
organizer

boolean

僅供輸出。參與者是否為主辦者。預設：false。

聯集欄位 _self。

_self 只能是下列其中一項：
self

boolean

僅供輸出。這個項目是否代表顯示活動副本的日曆。預設：false。

聯集欄位 _resource。

_resource 只能是下列其中一項：
resource

boolean

(選用步驟) 出席者是否為資源 (例如會議室)。不可變更，只能在最初新增出席者時設定。預設：false。

聯集欄位 _optional_attendee。

_optional_attendee 只能是下列其中一項：
optionalAttendee

boolean

(選用步驟) 列席者是否為選填項目。預設：false。

聯集欄位 _response_status。

_response_status 只能是下列其中一項：
responseStatus

string

(選用步驟) 回應狀態。可能的值為：

  • needsAction - 邀請對象尚未回覆邀請 (建議用於新活動)。
  • declined - 受邀者已拒絕邀請。
  • tentative - 參與者已暫時接受邀請。
  • accepted - 參與者已接受邀請。

聯集欄位 _comment。

_comment 只能是下列其中一項：
comment

string

僅供輸出。回覆留言。

聯集欄位 _additional_guests。

_additional_guests 只能是下列其中一項：
additionalGuests

integer

(選用步驟) 額外房客人數。預設：0。

附件

JSON 表示法 
{

  "fileUrl": string

  "title": string
}
欄位

聯集欄位 _file_url。

_file_url 只能是下列其中一項：
fileUrl

string

必填。附件的網址連結。

聯集欄位 _title。

_title 只能是下列其中一項：
title

string

(選用步驟) 附件名稱。

GuestPermissions

JSON 表示法 
{

  "guestsCanInviteOthers": boolean

  "guestsCanModify": boolean

  "guestsCanSeeGuests": boolean
}
欄位

聯集欄位 _guests_can_invite_others。

_guests_can_invite_others 只能是下列其中一項：
guestsCanInviteOthers

boolean

(選用步驟) 邀請對象是否可以邀請其他人。

聯集欄位 _guests_can_modify。

_guests_can_modify 只能是下列其中一項：
guestsCanModify

boolean

(選用步驟) 邀請對象是否可以修改活動。

聯集欄位 _guests_can_see_guests。

_guests_can_see_guests 只能是下列其中一項：
guestsCanSeeGuests

boolean

(選用步驟) 邀請對象是否能查看其他邀請對象。

WorkingLocationProperties

JSON 表示法 
{

  "type": enum (WorkingLocationType)

  "customLocationLabel": string
}
欄位

聯集欄位 _type。

_type 只能是下列其中一項：
type

enum (WorkingLocationType)

(選用步驟) 工作地點類型。

聯集欄位 _custom_location_label。

_custom_location_label 只能是下列其中一項：
customLocationLabel

string

(選用步驟) 自訂位置的標籤。如果類型為 CUSTOM_LOCATION，則為必要欄位。

EventType

事件類型。建立後即無法變更。

列舉
EVENT_TYPE_UNSPECIFIED 視為 DEFAULT。
DEFAULT 定期活動。預設值。
OUT_OF_OFFICE 不在辦公室的活動。
FOCUS_TIME 專注時間活動。
WORKING_LOCATION 工作地點活動。
BIRTHDAY 每年舉辦的全天特別活動。
FROM_GMAIL Gmail 中的活動。無法建立這類活動。

WorkingLocationType

工作地點類型。

列舉
WORKING_LOCATION_TYPE_UNSPECIFIED 未指定工作地點類型。系統會將其視為 HOME_OFFICE。
HOME_OFFICE 居家辦公室。
CUSTOM_LOCATION 自訂位置。

可用性

活動的供應情形設定。

列舉
AVAILABILITY_UNSPECIFIED 預設。視為 BUSY。
AVAILABILITY_BUSY 在日曆上封鎖時間。
AVAILABILITY_FREE 不會封鎖時間。

工具註解

破壞性提示：❌ | 等冪提示：✅ | 唯讀提示：✅ | 開放世界提示：❌