MCP Tools Reference: calendarmcp.googleapis.com

Công cụ: list_events

Trả về các sự kiện trên lịch đã cho khớp với tất cả các điều kiện ràng buộc được chỉ định. Bạn không nên chỉ định các hạn chế về thời gian, trừ phi người dùng yêu cầu. Đối với các cụm từ tìm kiếm dựa trên chủ đề hoặc từ khoá không giới hạn trên lịch chính, bạn phải sử dụng công cụ search_events.

Mẫu sau đây minh hoạ cách sử dụng curl để gọi công cụ MCP list_events.

Yêu cầu 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
}'

Giản đồ đầu vào

ListEventsRequest

Biểu diễn dưới dạng JSON 
{
  "eventTypeFilter": [
    string
  ],
  "eventType": [
    enum (EventType)
  ],

  "calendarId": string

  "pageSize": integer

  "pageToken": string

  "startTime": string

  "endTime": string

  "timeZone": string

  "orderBy": string

  "fullText": string
}
Trường
eventTypeFilter[]
(deprecated)

string

Không bắt buộc. Không dùng nữa: hãy sử dụng event_type.
eventType[]

enum (EventType)

Không bắt buộc. Các loại sự kiện cần trả về. Nếu trống, chỉ các loại sự kiện sau được trả về: DEFAULT, OUT_OF_OFFICE, FOCUS_TIME, FROM_GMAIL

Trường nhóm _calendar_id.

_calendar_id chỉ có thể là một trong những trạng thái sau:
calendarId

string

Không bắt buộc. Mã của lịch chứa các sự kiện. Địa chỉ email – có thể được phân giải bằng list_calendars. Mặc định: lịch chính.

Trường nhóm _page_size.

_page_size chỉ có thể là một trong những trạng thái sau:
pageSize

integer

Không bắt buộc. Số sự kiện tối đa trên mỗi trang (mặc định là 100, tối đa là 250). Nên dùng: 10.

Trường nhóm _page_token.

_page_token chỉ có thể là một trong những trạng thái sau:
pageToken

string

Không bắt buộc. Mã thông báo trang tiếp theo. Sử dụng giá trị nextPageToken của trang trước.

Trường nhóm _start_time.

_start_time chỉ có thể là một trong những trạng thái sau:
startTime

string

Không bắt buộc. Giới hạn dưới của một khoảng thời gian. Chỉ được đặt khi người dùng yêu cầu một khung thời gian cụ thể. Phải là dấu thời gian ISO 8601 nhỏ hơn end_time.

Trường nhóm _end_time.

_end_time chỉ có thể là một trong những trạng thái sau:
endTime

string

Không bắt buộc. Giới hạn trên của một khoảng thời gian. Chỉ được đặt khi người dùng yêu cầu một khung thời gian cụ thể hoặc một thời điểm trong quá khứ. Phải là dấu thời gian ISO 8601 lớn hơn start_time.

Trường nhóm _time_zone.

_time_zone chỉ có thể là một trong những trạng thái sau:
timeZone

string

Không bắt buộc. Múi giờ (mã nhận dạng IANA, ví dụ: Europe/Zurich) dùng để phân giải các ngày không có múi giờ. Mặc định: múi giờ của lịch.

Trường nhóm _order_by.

_order_by chỉ có thể là một trong những trạng thái sau:
orderBy

string

Không bắt buộc. Thứ tự trả về các sự kiện. Các giá trị có thể là:

  • default – Chưa chỉ định, nhưng có thứ tự xác định (mặc định).
  • startTime – Sắp xếp theo thời gian bắt đầu tăng dần.
  • startTimeDesc – Sắp xếp theo thời gian bắt đầu giảm dần.
  • lastModified – Sắp xếp theo thời gian sửa đổi gần đây nhất theo thứ tự tăng dần.

Trường nhóm _full_text.

_full_text chỉ có thể là một trong những trạng thái sau:
fullText

string

Không bắt buộc. Tìm kiếm không phân biệt chữ hoa chữ thường theo biểu mẫu tự do, khớp với tiêu đề, nội dung mô tả, vị trí hoặc người tham dự. Khớp với những sự kiện chứa tất cả các cụm từ tìm kiếm nguyên văn (tìm kiếm AND).

EventType

Loại sự kiện. Không thể thay đổi sau khi tạo.

Enum
EVENT_TYPE_UNSPECIFIED Được coi là DEFAULT.
DEFAULT Sự kiện định kỳ. Giá trị mặc định.
OUT_OF_OFFICE Sự kiện không có mặt tại văn phòng.
FOCUS_TIME Sự kiện thời gian cần tập trung.
WORKING_LOCATION Sự kiện về địa điểm làm việc.
BIRTHDAY Sự kiện đặc biệt kéo dài cả ngày và diễn ra hằng năm.
FROM_GMAIL Sự kiện từ Gmail. Bạn không thể tạo loại sự kiện này.

Giản đồ đầu ra

ListEventsResponse

Biểu diễn dưới dạng JSON 
{
  "summary": string,
  "description": string,
  "updated": string,
  "timeZone": string,
  "accessRole": string,
  "defaultReminders": [
    {
      object (Reminder)
    }
  ],
  "events": [
    {
      object (Event)
    }
  ],

  "nextPageToken": string
}
Trường
summary

string

Tiêu đề của lịch.
description

string

Nội dung mô tả về lịch.
updated

string

Thời gian cập nhật gần đây nhất (ISO 8601) của lịch.
timeZone

string

Múi giờ của lịch.
accessRole

string

Chỉ có đầu ra. Vai trò truy cập của người dùng đối với lịch. Các giá trị có thể là:

  • none – Không có quyền truy cập.
  • freeBusyReader – Quyền đọc thông tin rảnh/bận.
  • reader – Quyền đọc lịch. Các sự kiện riêng tư sẽ xuất hiện, nhưng thông tin chi tiết về sự kiện sẽ bị ẩn.
  • writer – Quyền đọc và ghi. Các sự kiện riêng tư sẽ xuất hiện và thông tin chi tiết về sự kiện sẽ hiển thị.
  • owner – Quyền truy cập của người quản lý, bao gồm cả khả năng sửa đổi chế độ cài đặt chia sẻ của lịch.
Quan trọng: Vai trò owner khác với chủ sở hữu dữ liệu của lịch. Một lịch chỉ có một chủ sở hữu dữ liệu, nhưng có thể có nhiều người dùng có vai trò owner.
defaultReminders[]

object (Reminder)

Lời nhắc mặc định cho các sự kiện trên lịch.
events[]

object (Event)

Danh sách sự kiện.

Trường nhóm _next_page_token.

_next_page_token chỉ có thể là một trong những trạng thái sau:
nextPageToken

string

Mã thông báo trang tiếp theo. Bị bỏ qua nếu không có trang tiếp theo.

Lời nhắc

Biểu diễn dưới dạng JSON 
{

  "method": string

  "minutes": integer
}
Trường

Trường nhóm _method.

_method chỉ có thể là một trong những trạng thái sau:
method

string

Bắt buộc. Phương thức phân phối. Các giá trị có thể là:

  • email – Lời nhắc được gửi qua email.
  • popup – Lời nhắc được gửi qua cửa sổ bật lên trên giao diện người dùng.

Trường nhóm _minutes.

_minutes chỉ có thể là một trong những trạng thái sau:
minutes

integer

Bắt buộc. Số phút trước khi lời nhắc được kích hoạt.

Sự kiện

Biểu diễn dưới dạng 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)
}
Trường
id

string

Giá trị nhận dạng riêng biệt.
status

string

Không bắt buộc. Trạng thái. Các giá trị có thể là:

  • confirmed – Sự kiện đã được xác nhận (mặc định).
  • tentative – Sự kiện đã được xác nhận tạm thời.
  • cancelled – Sự kiện bị huỷ hoặc bị xoá.
htmlLink

string

Chỉ có đầu ra. Đường liên kết tuyệt đối đến sự kiện này trong giao diện người dùng web của Lịch Google.
created

string

Chỉ có đầu ra. Thời gian tạo (ISO 8601).
updated

string

Chỉ có đầu ra. Thời gian sửa đổi lần gần đây nhất (ISO 8601).
summary

string

Tiêu đề.
description

string

Không bắt buộc. Nội dung mô tả. Có thể chứa HTML.
location

string

Không bắt buộc. Vị trí.
creator

object (Principal)

Chỉ có đầu ra. Nhà sáng tạo.
organizer

object (Principal)

Chỉ có đầu ra. Đơn vị tổ chức. Cũng có tên trong danh sách người tham dự nếu tham dự.
start

object (DateOrDateTime)

Thời gian bắt đầu (bao gồm cả giá trị đầu và giá trị cuối). Đối với sự kiện định kỳ, hệ thống sẽ sử dụng lần diễn ra đầu tiên.
end

object (DateOrDateTime)

Thời gian kết thúc (loại trừ). Đối với các sự kiện định kỳ, hệ thống sẽ sử dụng phiên bản đầu tiên.
recurrence[]

string

Quy tắc định kỳ dưới dạng chuỗi RRULE, EXRULE, RDATE hoặc EXDATE (theo RFC 5545). Bị bỏ qua đối với sự kiện diễn ra một lần. Bạn phải đặt thời gian bắt đầu/kết thúc trong các trường start/end.
recurringEventId

string

Mã sự kiện định kỳ mẹ cho các phiên bản của sự kiện định kỳ.
originalStartTime

object (DateOrDateTime)

Thời gian bắt đầu ban đầu của các sự kiện định kỳ. Đây là thời điểm phiên bản này sẽ bắt đầu theo dữ liệu định kỳ.
transparency
(deprecated)

string

Không bắt buộc. Không dùng nữa: hãy sử dụng availability.
visibility

string

Không bắt buộc. Chế độ hiển thị của sự kiện. Các giá trị có thể là:

  • default – Sử dụng chế độ hiển thị mặc định cho các sự kiện trên lịch. Đây là giá trị mặc định.
  • public – Tất cả người đọc lịch đều có thể xem thông tin chi tiết về sự kiện.
  • private – Chỉ những người tham dự sự kiện mới có thể xem thông tin chi tiết về sự kiện.

attendees[]

object (Attendee)

Người tham dự.
conferenceUrl

string

Đường liên kết đến hội nghị truyền hình.
colorId

string

Màu của sự kiện. Chỉ ảnh hưởng đến chế độ xem lịch của riêng bạn. Đây là mã nhận dạng đề cập đến một mục trong bảng màu của lịch (chuỗi '1' – '11'):

  • 1: Oải hương
  • 2: Xanh xám
  • 3: Nho
  • 4: Flamingo
  • 5: Chuối
  • 6: Màu quýt
  • 7: Màu xanh chim công
  • 8: Màu than chì
  • 9: Việt quất
  • 10: Húng quế
  • 11: Cà chua.

overrideReminders[]

object (Reminder)

Lời nhắc. Quay lại chế độ cài đặt mặc định của lịch nếu chưa được đặt.
attachments[]

object (Attachment)

Tệp đính kèm.
guestPermissions

object (GuestPermissions)

Quyền của khách.
eventType

enum (EventType)

Loại sự kiện.
workingLocationProperties

object (WorkingLocationProperties)

Thuộc tính địa điểm làm việc. Chỉ được điền sẵn khi event_type là WORKING_LOCATION.
availability

enum (Availability)

Không bắt buộc. Chế độ cài đặt tình trạng rảnh/bận.

Tổng

Biểu diễn dưới dạng JSON 
{
  "email": string,
  "displayName": string,
  "self": boolean
}
Trường
email

string

Email.
displayName

string

Tên.
self

boolean

Chỉ có đầu ra. Liệu người dùng này có tương ứng với lịch mà bản sao của sự kiện này xuất hiện hay không. Mặc định: false.

DateOrDateTime

Biểu diễn dưới dạng JSON 
{
  "date": string,
  "dateTime": string,
  "timeZone": string
}
Trường
date

string

Ngày theo tiêu chuẩn ISO 8601 vào nửa đêm theo giờ UTC (ví dụ: '2019-11-20T00:00:00Z').
dateTime

string

Dấu thời gian ISO 8601 (ví dụ: '2019-11-20T08:19:06-07:00').
timeZone

string

Tên múi giờ TZDB.

Người tham dự

Biểu diễn dưới dạng JSON 
{

  "id": string

  "email": string

  "displayName": string

  "organizer": boolean

  "self": boolean

  "resource": boolean

  "optionalAttendee": boolean

  "responseStatus": string

  "comment": string

  "additionalGuests": integer
}
Trường

Trường nhóm _id.

_id chỉ có thể là một trong những trạng thái sau:
id

string

Chỉ có đầu ra. Mã hồ sơ.

Trường nhóm _email.

_email chỉ có thể là một trong những trạng thái sau:
email

string

Bắt buộc. Địa chỉ email của người tham dự.

Trường nhóm _display_name.

_display_name chỉ có thể là một trong những trạng thái sau:
displayName

string

Không bắt buộc. Tên.

Trường nhóm _organizer.

_organizer chỉ có thể là một trong những trạng thái sau:
organizer

boolean

Chỉ có đầu ra. Người tham dự có phải là người tổ chức hay không. Mặc định: false.

Trường nhóm _self.

_self chỉ có thể là một trong những trạng thái sau:
self

boolean

Chỉ có đầu ra. Liệu mục này có đại diện cho lịch mà bản sao này của sự kiện xuất hiện hay không. Mặc định: false.

Trường nhóm _resource.

_resource chỉ có thể là một trong những trạng thái sau:
resource

boolean

Không bắt buộc. Người tham dự có phải là tài nguyên (ví dụ: phòng) hay không. Không thể thay đổi, chỉ có thể đặt khi người tham dự được thêm lần đầu. Mặc định: false.

Trường nhóm _optional_attendee.

_optional_attendee chỉ có thể là một trong những trạng thái sau:
optionalAttendee

boolean

Không bắt buộc. Người tham dự có phải là không bắt buộc hay không. Mặc định: false.

Trường nhóm _response_status.

_response_status chỉ có thể là một trong những trạng thái sau:
responseStatus

string

Không bắt buộc. Trạng thái phản hồi. Các giá trị có thể là:

  • needsAction – Người tham dự chưa phản hồi lời mời (nên dùng cho các sự kiện mới).
  • declined – Người tham dự đã từ chối lời mời.
  • tentative – Người tham dự đã dự kiến sẽ chấp nhận lời mời.
  • accepted – Khách mời đã chấp nhận lời mời.

Trường nhóm _comment.

_comment chỉ có thể là một trong những trạng thái sau:
comment

string

Chỉ có đầu ra. Bình luận phản hồi.

Trường nhóm _additional_guests.

_additional_guests chỉ có thể là một trong những trạng thái sau:
additionalGuests

integer

Không bắt buộc. Số lượng khách bổ sung. Mặc định: 0.

Tệp đính kèm

Biểu diễn dưới dạng JSON 
{

  "fileUrl": string

  "title": string
}
Trường

Trường nhóm _file_url.

_file_url chỉ có thể là một trong những trạng thái sau:
fileUrl

string

Bắt buộc. Đường liên kết URL đến tệp đính kèm.

Trường nhóm _title.

_title chỉ có thể là một trong những trạng thái sau:
title

string

Không bắt buộc. Tên tệp đính kèm.

GuestPermissions

Biểu diễn dưới dạng JSON 
{

  "guestsCanInviteOthers": boolean

  "guestsCanModify": boolean

  "guestsCanSeeGuests": boolean
}
Trường

Trường nhóm _guests_can_invite_others.

_guests_can_invite_others chỉ có thể là một trong những trạng thái sau:
guestsCanInviteOthers

boolean

Không bắt buộc. Khách có thể mời người khác hay không.

Trường nhóm _guests_can_modify.

_guests_can_modify chỉ có thể là một trong những trạng thái sau:
guestsCanModify

boolean

Không bắt buộc. Khách có thể sửa đổi sự kiện hay không.

Trường nhóm _guests_can_see_guests.

_guests_can_see_guests chỉ có thể là một trong những trạng thái sau:
guestsCanSeeGuests

boolean

Không bắt buộc. Cho biết khách có thể xem những khách khác hay không.

WorkingLocationProperties

Biểu diễn dưới dạng JSON 
{

  "type": enum (WorkingLocationType)

  "customLocationLabel": string
}
Trường

Trường nhóm _type.

_type chỉ có thể là một trong những trạng thái sau:
type

enum (WorkingLocationType)

Không bắt buộc. Loại địa điểm làm việc.

Trường nhóm _custom_location_label.

_custom_location_label chỉ có thể là một trong những trạng thái sau:
customLocationLabel

string

Không bắt buộc. Nhãn của một vị trí tuỳ chỉnh. Bắt buộc nếu loại là CUSTOM_LOCATION.

EventType

Loại sự kiện. Không thể thay đổi sau khi tạo.

Enum
EVENT_TYPE_UNSPECIFIED Được coi là DEFAULT.
DEFAULT Sự kiện định kỳ. Giá trị mặc định.
OUT_OF_OFFICE Sự kiện không có mặt tại văn phòng.
FOCUS_TIME Sự kiện thời gian cần tập trung.
WORKING_LOCATION Sự kiện về địa điểm làm việc.
BIRTHDAY Sự kiện đặc biệt kéo dài cả ngày và diễn ra hằng năm.
FROM_GMAIL Sự kiện từ Gmail. Bạn không thể tạo loại sự kiện này.

WorkingLocationType

Loại địa điểm làm việc.

Enum
WORKING_LOCATION_TYPE_UNSPECIFIED Loại địa điểm làm việc chưa được chỉ định. Sẽ được coi là HOME_OFFICE.
HOME_OFFICE Văn phòng tại nhà.
CUSTOM_LOCATION Vị trí tuỳ chỉnh.

Phạm vi cung cấp

Chế độ cài đặt tình trạng rảnh/bận cho một sự kiện.

Enum
AVAILABILITY_UNSPECIFIED Mặc định. Được coi là BUSY.
AVAILABILITY_BUSY Chặn thời gian trên lịch.
AVAILABILITY_FREE Không chặn thời gian.

Chú giải công cụ

Gợi ý phá hoại: ❌ | Gợi ý bất biến: ✅ | Gợi ý chỉ đọc: ✅ | Gợi ý thế giới mở: ❌

Phạm vi cấp phép

Yêu cầu một trong các phạm vi OAuth sau:

  • 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