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ư trích đoạn nội dung thư, tiêu đề, người gửi, người nhận, v.v. Xin lưu ý rằng công cụ này không trả về toàn bộ nội dung thư; hãy 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 đó 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ụ search_threads MCP.

Yêu cầu Curl 
curl --location 'https://gmailmcp.googleapis.com/mcp/v1' \
--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
}
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 luồng 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 đều được liệt kê (ngoại trừ thư rác và thư bị xoá theo mặc định).

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

Người gửi và người nhận: from: – Do một người cụ thể gửi. to: – Gửi cho một người cụ thể. cc: – Những người cụ thể trong danh sách Cc. bcc: – Những người cụ thể trong trường Bcc. deliveredto: – Đã gửi đến một địa chỉ cụ thể. list: – 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 sau một ngày. before:YYYY/MM/DD / older:YYYY/MM/DD – Nhận trước một ngày. older_than: – Cũ hơn một khoảng thời gian (ví dụ: 1y, 2d). newer_than: – Mới hơn một khoảng thời gian.

Nội dung: subject: – Từ trong dòng chủ đề. has: – Có các loại nội dung cụ thể (tệp đính kèm, ổ đĩa, YouTube, tài liệu). filename: – Tệp đính kèm có tên hoặc loại cụ thể. "<từ/cụm từ>" – Tìm một từ hoặc cụm từ chính xác. (ví dụ: "ngày lễ", "kỳ nghỉ lễ"). + – Khớp chính xác một từ. (ví dụ: +holiday, +unicorn) rfc822msgid: – Tiêu đề mã nhận dạng thư cụ thể. AROUND – Tìm các từ gần nhau (ví dụ: holiday AROUND 10 vacation).

Nhãn và danh mục: label: – Có nhãn cụ thể. Công cụ này chấp nhận mã nhận dạng 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: – 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ỗ, giao dịch mua). in:

Trạng thái: is: – 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: – Kích thước cụ thể tính bằng byte. larger: / smaller: – 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 – Khớp tất cả tiêu chí (hành vi mặc định). OR hoặc { } – 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ụ: -phim). ( ) – 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ả bản nháp trong THÙNG RÁC trong kết quả. Giá trị mặc định là false.

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
}
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ể được dùng trong một 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.

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 luồng.
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
  ]
}
Trường
id

string

Giá trị nhận dạng riêng biệ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 đầy đủ của phần nội dung, 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.

Chú giải công cụ

Gợi ý phá huỷ: ❌ | Gợi ý không thay đổi giá trị: ✅ | Gợi ý chỉ đọc: ✅ | Gợi ý thế giới mở: ❌