MCP Tools Reference: gmailmcp.googleapis.com

Công cụ: search_threads

Liệt kê các chuỗi email trong tài khoản Gmail của người dùng đã xác thực.

Công cụ này có thể lọc các luồng dựa trên một chuỗi truy vấn và hỗ trợ phân trang. Phương thức này trả về danh sách các chuỗi, bao gồm cả mã nhận dạng và các thông báo liên quan. Mỗi thông báo liên quan đều chứa các thông tin chi tiết như đoạn trích nội dung thư, tiêu đề, người gửi, người nhận, v.v. Tham số view kiểm soát những trường được điền sẵn trong các thông báo liên quan. Theo mặc định (hoặc với THREAD_VIEW_MINIMAL), chế độ này bao gồm tiêu đề và đoạn trích. Sử dụng THREAD_VIEW_METADATA_ONLY để loại trừ tiêu đề và đoạn trích. Xin lưu ý rằng công cụ này không trả về toàn bộ nội dung thư; hãy sử dụng công cụ "get_thread" với mã nhận dạng chuỗi để tìm nạp toàn bộ nội dung thư nếu cần. Những chuỗi có tiêu chí bị loại trừ vẫn có thể xuất hiện trong kết quả. Điều này xảy ra vì Gmail xác định các thư trùng khớp trước. Ví dụ: nếu bạn tìm kiếm -is:starred, Gmail sẽ tìm thấy toàn bộ chuỗi thư nếu chuỗi thư đó có ít nhất một thư không có dấu sao, ngay cả khi các email khác trong cùng cuộc trò chuyện đó có dấu sao.

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

Yêu cầu Curl 
curl --location 'https://gmailmcp.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": "search_threads",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Giản đồ đầu vào

Thông báo yêu cầu cho RPC SearchThreads.

SearchThreadsRequest

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

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean

  "view": enum (ThreadView)
}
Trường

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ố lượng chuỗi tối đa cần trả về. Nếu không được chỉ định, giá trị mặc định là 20. Giá trị tối đa được phép là 50.

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 để truy xuất một trang kết quả cụ thể trong danh sách. Để trống để tìm nạp trang đầu tiên. Tham số này chủ yếu được dùng để phân trang nhằm tiếp tục tìm nạp kết quả từ nơi mà lệnh gọi SearchThreads trước đó đã dừng lại, đặc biệt là khi số lượng chuỗi khớp với truy vấn vượt quá giới hạn page_size.

Trường nhóm _query.

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

string

Không bắt buộc. Một chuỗi truy vấn để lọc các chuỗi. Bạn phải chuyển đổi trước các cụm từ tìm kiếm bằng ngôn ngữ tự nhiên thành cụm từ tìm kiếm theo cú pháp của Gmail để sử dụng công cụ này. Nếu bạn bỏ qua tham số này, tất cả các chuỗi (ngoại trừ thư rác và thư bị xoá theo mặc định) sẽ được liệt kê.

Các toán tử được hỗ trợ theo danh mục:

Người gửi và người nhận:

  • from:<email> – Do một người cụ thể gửi.
  • to:<email> – Gửi cho một người cụ thể.
  • cc:<email> – Những người cụ thể trong trường Cc.
  • bcc:<email> – Một số người cụ thể trong trường Bcc.
  • deliveredto:<email> – Đã giao đến một địa chỉ cụ thể.
  • list:<email> – Từ một danh sách gửi thư cụ thể.

Thời gian và ngày:

  • after:YYYY/MM/DD / newer:YYYY/MM/DD – Nhận được sau một ngày.
  • before:YYYY/MM/DD / older:YYYY/MM/DD – Nhận được trước một ngày.
  • older_than:<duration> – Cũ hơn một khoảng thời gian (ví dụ: 1y, 2d).
  • newer_than:<duration> – Mới hơn một khoảng thời gian.

Nội dung:

  • subject:<words> – Từ trong dòng tiêu đề.
  • has:<type> – Có các loại nội dung cụ thể (tệp đính kèm, ổ đĩa, YouTube, tài liệu).
  • filename:<name> – Tệp đính kèm có tên hoặc loại cụ thể.
  • "<word/phrase>" – Tìm kiếm một từ hoặc cụm từ chính xác. (ví dụ: "holiday", "holiday vacation").
  • +<word> – Khớp chính xác một từ. (ví dụ: +holiday, +unicorn)
  • rfc822msgid:<id> – Phần đầu thư chứa mã nhận dạng thư cụ thể.
  • AROUND <distance> – Tìm các từ gần nhau (ví dụ: holiday AROUND 10 vacation).

Nhãn và danh mục:

  • label:<name> – Trong một nhãn cụ thể. Công cụ này chấp nhận mã nhãn chứ không chấp nhận tên hiển thị. Sử dụng công cụ list_labels để lấy mã nhận dạng.
  • category:<name> – Trong một danh mục (chính, mạng xã hội, quảng cáo, tin cập nhật, diễn đàn, đặt chỗ, mua hàng).
  • in:<label> – Tìm kiếm trong các nhãn cụ thể (lưu trữ, tạm ẩn, thùng rác, đã gửi, hộp thư đến). Ví dụ: in:trash, in:inbox. Theo mặc định, các thư đã lưu trữ và thư đã gửi sẽ được đưa vào; hãy dùng -in:archive và -in:sent để loại trừ các thư này. Theo mặc định, công cụ sẽ loại trừ rõ ràng các bản nháp. Sử dụng in:inbox để giới hạn phạm vi tìm kiếm chỉ trong hộp thư đến.
  • has:userlabels – Có nhãn người dùng.
  • has:nouserlabels – Không có nhãn người dùng nào.
  • has:*-star – Màu sắc cụ thể của ngôi sao (nếu được bật, ví dụ: has:yellow-star).
  • in:draft – Tìm kiếm trong bản nháp. -in:draft có nghĩa là loại trừ bản nháp khỏi kết quả tìm kiếm.
  • in:sent – Tìm kiếm trong thư đã gửi.
  • in:anywhere – Tìm kiếm trong tất cả các thư mục (bao gồm cả thư rác và thùng rác).

Trạng thái:

  • is:<status> – Tìm kiếm theo trạng thái (quan trọng, có gắn dấu sao, chưa đọc, đã đọc, bị tắt thông báo).

Kích thước:

  • size:<bytes> – Kích thước cụ thể tính bằng byte.
  • larger:<size> / smaller:<size> – Lớn hơn hoặc nhỏ hơn một kích thước (ví dụ: 10M cho 10 MB).

Logic và nhóm:

  • AND – So khớp tất cả tiêu chí (hành vi mặc định).
  • OR hoặc { } – Trùng khớp một hoặc nhiều tiêu chí (ví dụ: from:amy OR from:david, {from:amy from:david}).
  • - (dấu trừ) – Loại trừ tiêu chí (ví dụ: -movie).
  • ( ) – Nhóm nhiều cụm từ tìm kiếm (ví dụ: subject:(dinner film)).

Ví dụ:

  • subject:OneMCP Update
  • from:user@example.com
  • to:user2@example.com AND newer_than:7d
  • project proposal has:attachment
  • is:unread -in:draft

Trường nhóm _include_trash.

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

boolean

Không bắt buộc. Bao gồm cả các chuỗi trong THÙNG RÁC trong kết quả. Giá trị mặc định là false.

Trường nhóm _view.

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

enum (ThreadView)

Không bắt buộc. Kiểm soát các trường được điền sẵn cho các chuỗi trong danh sách chuỗi. Giá trị mặc định là THREAD_VIEW_MINIMAL. THREAD_VIEW_MINIMAL trả về id, đoạn trích, tiêu đề, người gửi, người nhận, người nhận bản sao, ngày, labelIds. THREAD_VIEW_METADATA_ONLY trả về id, from, to, cc, date, labelIds.

ThreadView

Enum để kiểm soát các trường được điền sẵn cho các chuỗi trong phản hồi ListThreads và SearchThreads.

Enum
THREAD_VIEW_UNSPECIFIED Ánh xạ đến THREAD_VIEW_MINIMAL để tương thích ngược.
THREAD_VIEW_METADATA_ONLY Trả về id, from, to, cc, date, labelIds.
THREAD_VIEW_MINIMAL Trả về id, đoạn trích, tiêu đề, người gửi, người nhận, người nhận bản sao, ngày, labelIds.

Giản đồ đầu ra

Thông báo phản hồi cho RPC SearchThreads.

SearchThreadsResponse

Biểu diễn dưới dạng JSON 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": string,
  "resultCountEstimate": string
}
Trường
threads[]

object (Thread)

Danh sách tóm tắt chuỗi cuộc trò chuyện.
nextPageToken

string

Một mã thông báo có thể dùng trong lệnh gọi tiếp theo để truy xuất trang tiếp theo của các chuỗi. Chỉ trình bày nếu có thêm kết quả. Nếu số lượng luồng khớp với truy vấn vượt quá giới hạn page_size, thì phản hồi sẽ chứa một next_page_token. Để truy xuất trang kết quả tiếp theo, hãy truyền mã thông báo này vào trường page_token của SearchThreadsRequest tiếp theo.
resultCountEstimate

string (int64 format)

Số lượng kết quả ước tính cho truy vấn này. Bạn nên coi đây là giới hạn dưới. Ví dụ: nếu giới hạn dưới là 500, thì bạn có thể báo cáo cho người dùng rằng số lượng là "500+".

Chuỗi hội thoại

Biểu diễn dưới dạng JSON 
{
  "id": string,
  "messages": [
    {
      object (Message)
    }
  ]
}
Trường
id

string

Giá trị nhận dạng duy nhất của chuỗi.
messages[]

object (Message)

Danh sách các tin nhắn trong chuỗi, được sắp xếp theo thứ tự thời gian.

Nhắn tin

Biểu diễn dưới dạng JSON 
{
  "id": string,
  "snippet": string,
  "subject": string,
  "sender": string,
  "toRecipients": [
    string
  ],
  "ccRecipients": [
    string
  ],
  "date": string,
  "plaintextBody": string,
  "attachmentIds": [
    string
  ],
  "htmlBody": string,
  "attachments": [
    {
      object (AttachmentMetadata)
    }
  ],
  "labelIds": [
    string
  ]
}
Trường
id

string

Giá trị nhận dạng duy nhất của thông báo.
snippet

string

Đoạn trích nội dung thư.
subject

string

Tiêu đề thư được trích xuất từ phần đầu thư:
sender

string

Địa chỉ email của người gửi.
toRecipients[]

string

Đến địa chỉ email của người nhận.
ccRecipients[]

string

Địa chỉ email của người nhận CC.
date

string

Ngày của thông báo ở định dạng ISO 8601 (YYYY-MM-DD).
plaintextBody

string

Nội dung toàn bộ phần thân, chỉ được điền sẵn nếu MessageFormat là FULL_CONTENT.
attachmentIds[]

string

Chỉ có đầu ra. Mã nhận dạng tệp đính kèm, chỉ được điền sẵn nếu MessageFormat là FULL_CONTENT.
htmlBody

string

Nội dung HTML của email, chỉ được điền sẵn nếu MessageFormat là FULL_CONTENT.
attachments[]

object (AttachmentMetadata)

Chỉ có đầu ra. Tệp đính kèm, chỉ được điền sẵn nếu MessageFormat là FULL_CONTENT.
labelIds[]

string

Mã nhận dạng của các nhãn được đính kèm vào thư. Bao gồm mã nhận dạng của nhãn người dùng và nhãn hệ thống tiêu chuẩn, giới hạn ở INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, SENT, DRAFT, CHAT.

AttachmentMetadata

Biểu diễn dưới dạng JSON 
{
  "id": string,
  "mimeType": string,
  "filename": string
}
Trường
id

string

Chỉ có đầu ra. Mã nhận dạng của tệp đính kèm.
mimeType

string

Loại MIME của tệp đính kèm.
filename

string

Tên tệp của tệp đính kèm.

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://mail.google.com/
  • https://www.googleapis.com/auth/gmail.modify
  • https://www.googleapis.com/auth/gmail.readonly