MCP Tools Reference: calendarmcp.googleapis.com

ツール: list_events

指定されたカレンダーで、指定されたすべての制約に一致するイベントを返します。ユーザーからリクエストされない限り、時間制約を指定しないでください。メインのカレンダーでキーワードやトピックに基づくオープン エンドの検索を行う場合は、代わりに search_events ツールを使用する必要があります。

次のサンプルは、curl を使用して list_events 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": "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

省略可。時間範囲の上限。ユーザーが特定の期間または過去の時間をリクエストした場合にのみ設定する必要があります。start_time より大きい ISO 8601 タイムスタンプである必要があります。

共用体フィールド _time_zone。

_time_zone は次のいずれかになります。
timeZone

string

省略可。タイムゾーンのない日付の解決に使用されるタイムゾーン（IANA ID、例: Europe/Zurich）。デフォルト: カレンダーのタイムゾーン。

共用体フィールド _order_by。

_order_by は次のいずれかになります。
orderBy

string

省略可。イベントが返される順序。有効な値は次のとおりです:

  • default - 未指定ですが、決定論的な順序付け（デフォルト）。
  • startTime - 開始時間で昇順に並べ替えます。
  • startTimeDesc - 開始時間の降順で並べ替えます。
  • lastModified - 最終更新日時の昇順で並べ替えます。

共用体フィールド _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 ロールは、カレンダーのデータ所有者とは異なります。カレンダーのデータ所有者は 1 人ですが、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

固有識別子。
status

string

省略可。ステータス。有効な値は次のとおりです:

  • confirmed - イベントが確定済み（デフォルト）。
  • tentative - イベントが仮確定されています。
  • cancelled - イベントがキャンセルまたは削除されました。
htmlLink

string

出力専用。Google カレンダーのウェブ UI でこの予定への絶対リンク。
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: Lavender
  • 2: Sage
  • 3: グレープ
  • 4: Flamingo
  • 5: Banana
  • 6: タンジェリン
  • 7: Peacock
  • 8: Graphite
  • 9: ブルーベリー
  • 10: バジル
  • 11: トマト。
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 の午前 0 時の 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

必須。添付ファイルへの URL リンク。

共用体フィールド _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
  • https://www.googleapis.com/auth/calendar.events.readonly
  • https://www.googleapis.com/auth/calendar.readonly