MCP Tools Reference: gmailmcp.googleapis.com

工具：search_threads

列出已驗證使用者 Gmail 帳戶中的電子郵件討論串。

這項工具可根據查詢字串篩選執行緒，並支援分頁。系統會傳回討論串清單，包括 ID 和相關訊息。每封相關郵件都會顯示詳細資料，例如郵件內文片段、主旨、寄件者、收件者等。請注意，這項工具不會傳回完整郵件內文；如要擷取完整郵件內文，請使用「get_thread」工具和執行緒 ID。結果中仍可能會出現符合排除條件的討論串，這是因為 Gmail 會先找出符合條件的郵件。舉例來說，如果搜尋 -is:starred，只要會話群組至少包含一封未加星號的郵件，Gmail 就會顯示整個會話群組，即使當中其他郵件已加星號也是如此。

以下範例示範如何使用 curl 叫用 search_threads MCP 工具。

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
}'

輸入內容的結構定義

SearchThreads 遠端程序呼叫的要求訊息。

SearchThreadsRequest

JSON 表示法 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean
}
欄位

聯集欄位 _page_size。

_page_size 只能是下列其中一項：
pageSize

integer

(選用步驟) 要傳回的執行緒數量上限。如未指定，則預設值為 20。允許的最大值為 50。

聯集欄位 _page_token。

_page_token 只能是下列其中一項：
pageToken

string

(選用步驟) 用來擷取清單中特定頁面結果的頁面符記。如要擷取第一頁，請留空。這項參數主要用於分頁，可從上一次 SearchThreads 呼叫停止的位置繼續擷取結果，特別是當符合查詢條件的執行緒數量超過 page_size 限制時。

聯集欄位 _query。

_query 只能是下列其中一項：
query

string

(選用步驟) 用於篩選對話串的查詢字串。如要使用這項工具，必須先將自然語言查詢轉換為 Gmail 語法查詢。如果省略，系統會列出所有討論串 (預設不包括垃圾郵件和垃圾桶)。

各類別支援的運算子：

寄件者和收件者：from: - 特定使用者傳送的郵件。 收件者： - 傳送給特定使用者。cc: - Specific people in Cc. 密件副本： - 密件副本中的特定使用者。deliveredto: - 傳送至特定地址。list: - 來自特定郵寄清單。

時間和日期：after:YYYY/MM/DD / newer:YYYY/MM/DD - 在特定日期後收到。before:YYYY/MM/DD / older:YYYY/MM/DD - 在指定日期前收到的郵件。older_than: - 較舊的期限 (例如 1y、2d)。 newer_than: - 比指定時間更近。

內容：主旨： - 主旨行中的字詞。has: - 含有特定內容類型 (附件、雲端硬碟、YouTube、文件)。filename: - 含有特定名稱或類型的附件。「<字詞/詞組>」：搜尋完全相符的字詞或詞組。(例如「holiday」、「holiday vacation」)。+ - 完全比對字詞。(例如 +holiday、+unicorn) rfc822msgid: - 特定郵件 ID 標頭。 AROUND - 尋找相鄰的字詞 (例如：holiday AROUND 10 vacation)。

標籤和類別：label: - 搜尋特定標籤下的郵件。這項工具接受標籤 ID，但不接受顯示名稱。使用 list_labels 工具取得 ID。category: - 類別 (主要、社群網路、促銷內容、最新快訊、論壇、預訂、購物交易)。in:

狀態：is: - 依狀態搜尋 (重要、已加星號、未讀取、已讀取、已設為靜音)。

大小：size: - 特定大小 (以位元組為單位)。larger: / smaller: - 大於或小於特定大小 (例如 10M 代表 10 MB)。

邏輯和分組：AND - 符合所有條件 (預設行為)。OR 或 { } - 比對一或多項條件 (例如：from:amy OR from:david、{from:amy from:david})。- (減號) - 排除條件 (例如 -movie)。( ) - 將多個搜尋字詞分組 (例如：subject:(dinner film))。

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

聯集欄位 _include_trash。

_include_trash 只能是下列其中一項：
includeTrash

boolean

(選用步驟) 在結果中包含垃圾桶中的草稿。預設值為 false。

輸出內容的結構定義

SearchThreads 遠端程序呼叫的回應訊息。

SearchThreadsResponse

JSON 表示法 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": string
}
欄位
threads[]

object (Thread)

對話串摘要清單。
nextPageToken

string

可在後續呼叫中使用的權杖，用於擷取下一頁的討論串。如果還有其他結果，才會顯示。如果符合查詢的討論串數量超過 page_size 上限，回應就會包含 next_page_token。如要擷取下一頁結果，請在下一個 SearchThreadsRequest 的 page_token 欄位中傳遞這個符記。

討論串

JSON 表示法 
{
  "id": string,
  "messages": [
    {
      object (Message)
    }
  ]
}
欄位
id

string

執行緒的專屬 ID。
messages[]

object (Message)

依時間順序排列的訊息串清單。

訊息

JSON 表示法 
{
  "id": string,
  "snippet": string,
  "subject": string,
  "sender": string,
  "toRecipients": [
    string
  ],
  "ccRecipients": [
    string
  ],
  "date": string,
  "plaintextBody": string,
  "attachmentIds": [
    string
  ]
}
欄位
id

string

訊息的專屬 ID。
snippet

string

郵件內文的程式碼片段。
subject

string

從標頭擷取的郵件主旨：
sender

string

寄件者的電子郵件地址。
toRecipients[]

string

收件者的電子郵件地址。
ccRecipients[]

string

副本收件者的電子郵件地址。
date

string

訊息日期，採用 ISO 8601 格式 (YYYY-MM-DD)。
plaintextBody

string

完整內文內容，只有在 MessageFormat 為 FULL_CONTENT 時才會填入。
attachmentIds[]

string

僅供輸出。附件 ID，只有在 MessageFormat 為 FULL_CONTENT 時才會填入。

工具註解

破壞性提示：❌ | 等冪提示：✅ | 唯讀提示：✅ | 開放世界提示：❌