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 역할은 캘린더의 데이터 소유자와 다릅니다. 캘린더에는 단일 데이터 소유자가 있지만 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 Calendar 웹 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: 라벤더
  • 2: 세이지
  • 3: 그레이프
  • 4: 플라밍고
  • 5: 바나나
  • 6: 귤
  • 7: 공작새
  • 8: 흑연
  • 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 자정의 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