MCP Tools Reference: calendarmcp.googleapis.com

工具：create_event

在指定日曆中建立活動。

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

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

輸入內容的結構定義

CreateEvent 的要求訊息。

CreateEventRequest

JSON 表示法 
{
  "summary": string,
  "startTime": string,
  "endTime": string,
  "attendeeEmails": [
    string
  ],
  "attendees": [
    {
      object (Attendee)
    }
  ],
  "recurrenceData": [
    string
  ],
  "overrideReminders": [
    {
      object (Reminder)
    }
  ],
  "attachments": [
    {
      object (Attachment)
    }
  ],

  "calendarId": string

  "description": string

  "location": string

  "allDay": boolean

  "timeZone": string

  "notificationLevel": enum (NotificationLevel)

  "addGoogleMeetUrl": boolean

  "visibility": string

  "colorId": string

  "googleMeetUrl": string

  "guestPermissions": {
    object (GuestPermissions)
  }

  "availability": enum (Availability)

  "eventType": enum (EventType)

  "workingLocationProperties": {
    object (WorkingLocationProperties)
  }
}
欄位
summary

string

必填。標題。
startTime

string

必填。開始時間 (ISO 8601，例如 '2026-04-30T10:00:00Z')。
endTime

string

必填。結束時間 (ISO 8601，例如 '2026-04-30T11:00:00Z')。
attendeeEmails[]
(deprecated)

string

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

object (Attendee)

(選用步驟) 活動與會者。如果使用者在主要日曆中建立活動，且至少有一位其他參與者，系統會自動將目前使用者新增為參與者 (如果尚未加入)。
recurrenceData[]

string

(選用步驟) 重複規則，格式為 RRULE、RDATE 或 EXDATE 字串 (依據 RFC 5545)。
overrideReminders[]

object (Reminder)

(選用步驟) 提醒事項會覆寫日曆預設設定。
attachments[]

object (Attachment)

(選用步驟) 檔案附件。

聯集欄位 _calendar_id。

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

string

(選用步驟) 要在哪個日曆中建立活動。電子郵件地址 - 可使用 list_calendars 解析。預設值：主要日曆。

聯集欄位 _description。

_description 只能是下列其中一項：
description

string

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

聯集欄位 _location。

_location 只能是下列其中一項：
location

string

(選用步驟) 。

聯集欄位 _all_day。

_all_day 只能是下列其中一項：
allDay

boolean

(選用步驟) 活動是否為全天活動。如為 true，系統會將開始/結束時間視為午夜。

聯集欄位 _time_zone。

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

string

(選用步驟) IANA 時區資料庫名稱 (例如 America/Los_Angeles)。預設值：使用者的主要時區。覆寫 start_time 和 end_time 中的偏移。

聯集欄位 _notification_level。

_notification_level 只能是下列其中一項：
notificationLevel

enum (NotificationLevel)

(選用步驟) 這項活動更新應傳送哪種電子郵件通知。

聯集欄位 _add_google_meet_url。

_add_google_meet_url 只能是下列其中一項：
addGoogleMeetUrl

boolean

(選用步驟) 建立並新增 Google Meet 網址。預設：false。

聯集欄位 _visibility。

_visibility 只能是下列其中一項：
visibility

string

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

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

聯集欄位 _color_id。

_color_id 只能是下列其中一項：
colorId

string

(選用步驟) 活動的顏色。如需顏色 ID 清單，請參閱 Event 資源的說明文件。

聯集欄位 _google_meet_url。

_google_meet_url 只能是下列其中一項：
googleMeetUrl

string

(選用步驟) 特定 Google Meet 網址或會議 ID。這會覆寫 add_google_meet_url。

聯集欄位 _guest_permissions。

_guest_permissions 只能是下列其中一項：
guestPermissions

object (GuestPermissions)

(選用步驟) 邀請對象權限。

聯集欄位 _availability。

_availability 只能是下列其中一項：
availability

enum (Availability)

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

聯集欄位 _event_type。

_event_type 只能是下列其中一項：
eventType

enum (EventType)

(選用步驟) 活動類型。

聯集欄位 _working_location_properties。

_working_location_properties 只能是下列其中一項：
workingLocationProperties

object (WorkingLocationProperties)

(選用步驟) 工作地點屬性 (如果 eventType 為 WORKING_LOCATION)。

參與者

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 - Attendee has not responded to the invitation (recommended for new events).
  • declined - 受邀者已拒絕邀請。
  • tentative - 與會者已暫時接受邀請。
  • accepted - 參與者已接受邀請。

聯集欄位 _comment。

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

string

僅供輸出。回覆留言。

聯集欄位 _additional_guests。

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

integer

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

提醒

JSON 表示法 
{

  "method": string

  "minutes": integer
}
欄位

聯集欄位 _method。

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

string

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

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

聯集欄位 _minutes。

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

integer

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

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

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

附件

JSON 表示法 
{

  "fileUrl": string

  "title": string
}
欄位

聯集欄位 _file_url。

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

string

必填。附件的網址連結。

聯集欄位 _title。

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

string

(選用步驟) 附件名稱。

WorkingLocationProperties

JSON 表示法 
{

  "type": enum (WorkingLocationType)

  "customLocationLabel": string
}
欄位

聯集欄位 _type。

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

enum (WorkingLocationType)

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

聯集欄位 _custom_location_label。

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

string

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

NotificationLevel

接收最新消息的電子郵件通知層級。

列舉
NOTIFICATION_LEVEL_UNSPECIFIED 預設。視為 ALL。
NONE 沒有通知。
EXTERNAL_ONLY 僅限外部出席者。
ALL 所有與會者。

可用性

活動的供應情形設定。

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

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 自訂位置。

輸出內容的結構定義

事件

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 - Attendee has not responded to the invitation (recommended for new events).
  • declined - 受邀者已拒絕邀請。
  • tentative - 與會者已暫時接受邀請。
  • accepted - 參與者已接受邀請。

聯集欄位 _comment。

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

string

僅供輸出。回覆留言。

聯集欄位 _additional_guests。

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

integer

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

提醒

JSON 表示法 
{

  "method": string

  "minutes": integer
}
欄位

聯集欄位 _method。

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

string

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

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

聯集欄位 _minutes。

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

integer

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

附件

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 不會封鎖時間。

工具註解

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

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/calendar
  • https://www.googleapis.com/auth/calendar.events