MCP Tools Reference: calendarmcp.googleapis.com

工具：get_event

從指定日曆傳回單一活動。

這項工具適用於以下查詢：

  • 取得團隊會議的詳細資料。
  • Show me the event with id event123 on my calendar.

範例：

get_event(
            eventId='event123'
        )
        # Returns the event details for the event with id `event123` on the user's primary calendar.

以下範例示範如何使用 curl 叫用 get_event 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": "get_event",
    "arguments": {
      // provide these details according to the tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

輸入內容的結構定義

GetEventRequest

JSON 表示法 
{
  "eventId": string,

  "calendarId": string
}
欄位
eventId

string

必填。要取得的活動 ID。

聯集欄位 _calendar_id。

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

string

(選用步驟) 要從中取得活動的日曆 ID。預設為使用者的主要日曆。

輸出內容的結構定義

事件

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)
    }
  ],
  "eventType": string,
  "conferenceUrl": string,
  "colorId": string,
  "overrideReminders": [
    {
      object (Reminder)
    }
  ]
}
欄位
id

string

事件的不透明 ID。建立新的單一或週期性活動時，可以指定活動 ID。提供的 ID 必須符合下列規則：

  • ID 允許的字元為 base32hex 編碼使用的字元，即小寫字母 a-v 和數字 0-9，請參閱 RFC2938 的 3.1.2 節
  • ID 長度必須介於 5 至 1,024 個半形字元之間
  • 每個日曆的 ID 不得重複

由於系統是全球分散式架構，我們無法保證在建立事件時偵測到 ID 衝突。為盡量降低發生衝突的風險，建議您使用已建立的 UUID 演算法，例如 RFC4122 中所述的演算法。

如未指定 ID，伺服器會自動產生。

請注意，icalUID 和 ID 並不相同，建立活動時只能提供其中一個。兩者語意上的差異在於，週期性活動中，一個活動的所有例項都有不同的 ID，但共用相同的 icalUID。
status

string

活動的狀態。(選用步驟) 可能的值為：

  • confirmed - 活動已確認。這是預設狀態。
  • tentative - 活動已暫時確認。
  • cancelled - 活動已取消 (已刪除)。只有在增量同步處理 (指定 syncToken 或 updatedMin 時) 或 showDeleted 標記設為 true 時，清單方法才會傳回已取消的事件。get 方法一律會傳回這些項目。

根據活動類型，「已取消」狀態代表兩種不同情況：

  1. 如果未取消的週期性活動有已取消的例外狀況，表示系統不應再向使用者顯示該活動。用戶端應在父項週期性活動的生命週期內儲存這些事件。系統只保證已取消的例外狀況會填入 ID、recurringEventId 和 originalStartTime 欄位的值。其他欄位可能會空白。
  2. 其他取消的活動則代表已刪除的活動。請客戶移除本機同步處理的副本。這類取消的活動最終會消失，因此請勿依賴這些活動。系統只保證已刪除的事件會填入 ID 欄位。

在主辦人的日曆中，已取消的活動仍會顯示活動詳細資料 (摘要、地點等)，方便主辦人還原 (取消刪除) 活動。同樣地，使用者受邀參加但手動移除的活動，仍會提供詳細資料。不過，如果增量同步要求將 showDeleted 設為 false，就不會傳回這些詳細資料。

如果活動變更發起人 (例如透過移動作業)，且原始發起人不在與會者清單中，系統會留下已取消的活動，且只會填入 ID 欄位。
htmlLink

string

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

string

活動的建立時間 (採用 ISO 8601 格式的時間戳記)。唯讀。
updated

string

主要事件資料的上次修改時間 (採用 ISO 8601 格式的時間戳記)。更新活動提醒不會導致這項設定變更。唯讀。
summary

string

活動名稱。
description

string

活動的說明。可包含 HTML。選填。
location

string

活動的地理位置，格式不限。選填。
creator

object (Principal)

活動建立者。唯讀。
organizer

object (Principal)

活動主辦人。如果主辦人也是參與者，參與者會以獨立項目顯示，且主辦人欄位設為 True。唯讀。
start

object (DateOrDateTime)

活動的開始時間 (包含在內)。如果是週期性活動，這是第一個例項的開始時間。
end

object (DateOrDateTime)

活動的結束時間 (不包含在內)。如果是週期性活動，這是指第一個例項的結束時間。
recurrence[]

string

週期性活動的 RRULE、EXRULE、RDATE 和 EXDATE 行清單，如 RFC5545 所指定。請注意，這個欄位不允許 DTSTART 和 DTEND 行；活動開始和結束時間是在開始和結束欄位中指定。如果是單一活動或週期性活動的執行個體，系統會省略這個欄位。
recurringEventId

string

如果是週期性活動的執行個體，這是該執行個體所屬週期性活動的 ID。不可變更。
originalStartTime

object (DateOrDateTime)

如果是週期性活動的例項，這是根據 recurringEventId 所識別週期性活動中的週期性資料，這個活動的開始時間。即使活動執行個體移至其他時間，這個 ID 仍可做為週期性活動系列中該執行個體的專屬 ID。不可變更。
transparency

string

活動是否會佔用日曆上的時間。(選用步驟) 可能的值為：

  • opaque - 預設值。活動會封鎖日曆上的時間。這相當於在日曆使用者介面中將「顯示為」設定為「忙碌」。
  • transparent - 活動不會在日曆上封鎖時間。這相當於在日曆使用者介面中將「顯示為」設定為「有空」。
visibility

string

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

  • default - 使用日曆中活動的預設顯示設定。這是預設值。
  • public - 活動為公開，日曆的所有讀者都能查看活動詳細資料。
  • private - 活動為私人活動，只有活動參與者可以查看活動詳細資料。
  • confidential - 活動為私人活動。提供這個值是為了相容性。
attendees[]

object (Attendee)

活動與會者。
eventType

string

事件的具體類型。建立活動後即無法修改這項設定。可能的值為：

  • birthday - 每年舉辦的全天活動。
  • default - 一般活動或未進一步指定。
  • focusTime - 專注時間活動。
  • fromGmail - Gmail 中的活動。無法建立這類活動。
  • outOfOffice - 不在辦公室的活動。
  • workingLocation - 工作地點活動。
conferenceUrl

string

活動的 Google Meet 會議連結。
colorId

string

活動顏色 ID (字串 1-11)：

  • 1：薰衣草色
  • 2：Sage
  • 3：葡萄
  • 4：Flamingo
  • 5：香蕉
  • 6：橙橘色
  • 7：孔雀
  • 8：石墨
  • 9：藍莓
  • 10：羅勒
  • 11：番茄。

在 Google 日曆中，活動顏色代表類別，可針對個別活動或系列活動設定。使用者可以在網頁版使用者介面中為顏色指派自訂標籤 (例如 1:1s、Break)，但 API 只會公開數字 ID，不會公開這些標籤。這項操作只會影響您自己的日曆檢視畫面，每位與會者都能控管自己的活動顏色。
overrideReminders[]

object (Reminder)

為這個活動定義的提醒事項，會覆寫日曆的預設提醒事項。如未設定，系統會使用日曆的預設提醒。

主體

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

string

主體 (日曆) 的電子郵件地址。
displayName

string

主體的名稱 (如有)。
self

boolean

這個主體是否對應於顯示這個活動副本的日曆。這個唯讀設定檔預設值為 False。

DateOrDateTime

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

string

採用 ISO 8601 格式的日期，以世界標準時間 (UTC) 午夜為準，例如 2019-11-20T00:00:00Z。如果設定這個欄位，就不得設定 date_time。
dateTime

string

採用 ISO 8601 格式的時間戳記，例如 2019-11-20T08:19:06-07:00 或 2019-11-20T08:19:06Z。如果設定這個欄位，就不得設定 date。
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

string

出席者的設定檔 ID (如有)。
email

string

如果有的話，請提供與會者的電子郵件地址。新增與會者時，必須提供這個欄位。必須是符合 RFC5322 規範的有效電子郵件地址。新增與會者時必須提供。
displayName

string

出席者的姓名 (如有)。選填。
organizer

boolean

出席者是否為活動主辦人。這個唯讀設定檔預設值為 False。
self

boolean

這個項目是否代表顯示活動副本的日曆。這個唯讀設定檔預設值為 False。
resource

boolean

出席者是否為資源。只有在首次將與會者新增至活動時，才能設定此項目。後續修改將遭到忽略。(選用步驟) 預設值為 False。
optionalAttendee

boolean

這是否為選填出席者。(選用步驟) 預設值為 False。
responseStatus

string

出席者的回覆狀態。可能的值為：

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

string

與會者的回覆留言。選填。
additionalGuests

integer

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

提醒

JSON 表示法 
{

  "method": string

  "minutes": integer
}
欄位

聯集欄位 _method。

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

string

必填。提醒傳送給使用者的管道。可能的值為：

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

聯集欄位 _minutes。

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

integer

必填。提醒事項應提前幾分鐘送達。

工具註解

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