MCP Tools Reference: calendarmcp.googleapis.com

ツール: list_events

指定された条件を満たす、指定されたカレンダーの予定を一覧表示します。

主な機能:

  • カレンダー ID（ユーザーのメイン カレンダーなど）。
  • 期間のフィルタリング。
  • 時間制約に一致するすべてのイベントを取得します。

次の場合は、可能であれば、代わりに search_events ツールを使用してユーザーのメイン カレンダーを検索します。

  • 特定のトピック、カテゴリ、インテント（「ランチミーティング」、「プロジェクトの同期」など）に一致するイベントをクエリしている。
  • 制約を満たすイベントをすべて見つけるのではなく、最も関連性の高い（上位 K 個の）イベントを見つける必要があります。
  • キーワード検索またはセマンティック検索の機能が必要である。

このツールは、次のようなクエリに使用します。

  • 明日のカレンダーの予定は？
  • 2025 年 7 月 14 日の予定は？
  • 来週の会議の予定を教えて
  • 今日の午後の予定の重複を確認する

  • 明日は太郎さんのミーティングがありますか？

例:

list_events(
            startTime='2024-09-17T06:00:00',
            endTime='2024-09-17T12:00:00',
            pageSize=10
        )
        # Returns up to 10 calendar events between 6:00 AM and 12:00 PM on September 17, 2024 from the user's primary calendar.

次のサンプルは、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
  ],

  "calendarId": string

  "pageSize": integer

  "pageToken": string

  "startTime": string

  "endTime": string

  "timeZone": string

  "orderBy": string

  "fullText": string
}
フィールド
eventTypeFilter[]

string

省略可。返されるイベントタイプ。次の値があります。

  • default - 通常のイベント（デフォルト）。
  • outOfOffice - 不在の予定。
  • focusTime - サイレント モードの予定。
  • workingLocation - 勤務場所イベント。
  • birthday - 誕生日イベント。
  • fromGmail - Gmail からの予定。

空の場合、default、outOfOffice、focusTime、fromGmail のイベントタイプのみが返されます。

共用体フィールド _calendar_id。

_calendar_id は次のいずれかになります。
calendarId

string

省略可。イベントを一覧表示するカレンダーの ID。デフォルトはユーザーのメイン カレンダーです。

共用体フィールド _page_size。

_page_size は次のいずれかになります。
pageSize

integer

省略可。1 つの結果ページで返されるイベントの最大数。クエリに一致するイベントが他にもある場合でも、結果のページのイベント数がこの値より少なくなることや、イベントがまったく含まれないことがあります。不完全なページは、レスポンスの next_page_token フィールドが空でないことで検出できます。デフォルトでは、値は 250 イベントです。ページサイズは 2,500 イベントを超えることはありません。

共用体フィールド _page_token。

_page_token は次のいずれかになります。
pageToken

string

省略可。返す結果ページを指定するトークン。

共用体フィールド _start_time。

_start_time は次のいずれかになります。
startTime

string

省略可。イベントの終了時間の境界値を含まない下限。この時刻より後に終了するイベントのみが返されます（つまり、検索する時間枠の開始）。start_time と end_time のどちらも指定されていない場合は、デフォルトで現在時刻が使用されます。指定する場合は、end_time 以下にする必要があります。ISO 8601 タイムスタンプである必要があります。たとえば、2026-06-03T10:00:00-07:00、2026-06-03T10:00:00Z、2026-06-03T10:00:00 などです。ミリ秒を指定できますが、無視されます。

共用体フィールド _end_time。

_end_time は次のいずれかになります。
endTime

string

省略可。イベントの開始時間の上限（境界値を含まない）。この時刻より前に開始したイベントのみが返されます（つまり、検索する時間枠の終了時刻）。指定する場合、start_time 以上にする必要があります。ISO 8601 タイムスタンプである必要があります。たとえば、2026-06-03T10:00:00-07:00、2026-06-03T10:00:00Z、2026-06-03T10:00:00 などです。ミリ秒を指定できますが、無視されます。

共用体フィールド _time_zone。

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

string

省略可。レスポンスで使用され、リクエスト内のタイムゾーンのない日付を解決するために使用されるタイムゾーン（IANA タイムゾーン データベース名（Europe/Zurich など）としてフォーマットされます）。デフォルトはカレンダーのタイムゾーンです。

共用体フィールド _order_by。

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

string

省略可。イベントが返される順序。次の値があります。

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

共用体フィールド _full_text。

_full_text は次のいずれかになります。
fullText

string

省略可。タイトル、説明、場所、参加者を検索するための自由形式の検索クエリ。

出力スキーマ

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 - ユーザーがカレンダーに対する管理者権限を持っている。このロールには、ライターロールのすべての権限に加えて、他のユーザーのアクセスレベルを表示および変更する権限が付与されています。重要: オーナーのロールは、カレンダーのデータオーナーとは異なります。カレンダーのデータオーナーは 1 人ですが、オーナーロールを持つユーザーは複数人設定できます。
defaultReminders[]

object (Reminder)

認証済みユーザーのカレンダーのデフォルトのリマインダー。これらのリマインダーは、明示的にオーバーライドされていない（override_reminders が設定されていない）このカレンダーのすべての予定に適用されます。
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)
    }
  ],
  "eventType": string,
  "conferenceUrl": string,
  "colorId": string,
  "overrideReminders": [
    {
      object (Reminder)
    }
  ]
}
フィールド
id

string

イベントの不透明な識別子。新しい単発イベントまたは定期的なイベントを作成するときに、ID を指定できます。指定された ID は、次のルールに従う必要があります。

  • ID に使用できる文字は、base32hex エンコードで使用される文字（英小文字 a ～ v と数字 0 ～ 9）です。RFC2938 のセクション 3.1.2 を参照してください。
  • ID の長さは 5 ～ 1,024 文字にする必要があります。
  • ID はカレンダーごとに一意である必要があります

システムがグローバルに分散しているため、イベントの作成時に ID の衝突が検出されるとは限りません。競合のリスクを最小限に抑えるため、RFC4122 で説明されているような確立された UUID アルゴリズムを使用することをおすすめします。

ID を指定しない場合、サーバーによって自動的に生成されます。

icalUID と ID は同一ではなく、イベントの作成時にいずれか一方のみを指定する必要があります。セマンティクスの違いの 1 つは、定期的な予定では、1 つの予定のすべてのインスタンスに異なる ID が割り当てられますが、それらはすべて同じ icalUID を共有していることです。
status

string

イベントのステータス。省略可。次の値があります。

  • confirmed - イベントが確定しています。これがデフォルトのステータスです。
  • tentative - イベントが仮確定しています。
  • cancelled - イベントがキャンセル（削除）されました。リストメソッドは、増分同期（syncToken または updatedMin が指定されている場合）でのみ、または showDeleted フラグが true に設定されている場合にのみ、キャンセルされたイベントを返します。get メソッドは常にそれらを返します。

キャンセル ステータスは、イベントタイプに応じて 2 つの異なる状態を表します。

  1. キャンセルされていない定期的な予定の例外がキャンセルされた場合、このインスタンスはユーザーに表示されなくなります。クライアントは、これらのイベントを親の定期的な予定の全期間保存する必要があります。キャンセルされた例外では、id、recurringEventId、originalStartTime の各フィールドに値が入力されることのみが保証されます。他のフィールドは空の場合があります。
  2. キャンセルされた他のすべてのイベントは、削除されたイベントを表します。クライアントはローカルで同期されたコピーを削除する必要があります。このようなキャンセルされたイベントは最終的に消滅するため、無期限に利用できるとは限りません。削除されたイベントでは、id フィールドのみが入力されることが保証されます。

主催者のカレンダーでは、キャンセルされた予定の詳細は（概要、場所など）引き続き表示され、復元（削除の取り消し）できます。同様に、ユーザーが招待され、手動で削除したイベントも、引き続き詳細を提供します。ただし、showDeleted が false に設定されている増分同期リクエストでは、これらの詳細は返されません。

イベントの主催者が変更され（移動オペレーションなど）、元の主催者が参加者リストにいない場合、キャンセルされたイベントが残ります。このイベントでは、id フィールドのみが入力されることが保証されます。
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)

イベントの主催者。主催者が参加者でもある場合は、参加者の別のエントリで、主催者フィールドが True に設定されます。読み取り専用です。
start

object (DateOrDateTime)

イベントの開始時刻（この時間も含まれます）。定期的な予定の場合、これは最初のインスタンスの開始時刻です。
end

object (DateOrDateTime)

イベントの終了時刻（含まれない）。定期的な予定の場合、これは最初のインスタンスの終了時刻です。
recurrence[]

string

RFC5545 で指定されている、定期的な予定の RRULE、EXRULE、RDATE、EXDATE 行のリスト。このフィールドでは DTSTART 行と DTEND 行は使用できません。イベントの開始時刻と終了時刻は、開始フィールドと終了フィールドで指定します。このフィールドは、単一のイベントまたは定期的なイベントのインスタンスでは省略されます。
recurringEventId

string

定期的な予定のインスタンスの場合、このインスタンスが属する定期的な予定の ID。変更できません。
originalStartTime

object (DateOrDateTime)

定期的な予定のインスタンスの場合、これは recurringEventId で識別される定期的な予定の繰り返しデータに従って、この予定が開始される時刻です。インスタンスが別の時間に移動された場合でも、定期的な予定シリーズ内のインスタンスを一意に識別します。変更できません。
transparency

string

予定がカレンダーの時間をブロックするかどうか。省略可。次の値があります。

  • opaque - デフォルト値。予定はカレンダーの時間をブロックします。これは、カレンダーの UI で [予定あり] に設定するのと同じです。
  • transparent - 予定はカレンダーの時間をブロックしません。これは、カレンダーの UI で [予定なし] に設定するのと同じです。
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: Peacock
  • 8: グラファイト
  • 9: ブルーベリー
  • 10: バジル
  • 11: トマト。

Google カレンダーでは、予定の色はカテゴリとして機能します。予定ごとまたはシリーズごとに設定できます。ユーザーはウェブ UI で色にカスタムラベル（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 の午前 0 時）。例: 2019-11-20T00:00:00Z。このフィールドが設定されている場合、date_time は設定できません。
dateTime

string

2019-11-20T08:19:06-07:00 や 2019-11-20T08:19:06Z などの ISO 8601 形式のタイムスタンプ。このフィールドが設定されている場合、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 です。

ツールのアノテーション

破壊的ヒント: ❌ | べき等ヒント: ✅ | 読み取り専用ヒント: ✅ | オープン ワールド ヒント: ❌