MCP Tools Reference: gmailmcp.googleapis.com

工具：search_threads

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

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

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

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

輸入內容的結構定義

SearchThreads RPC 的要求訊息。

SearchThreadsRequest

JSON 表示法 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean

  "view": enum (ThreadView)
}
欄位

聯集欄位 _page_size。

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

integer

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

聯集欄位 _page_token。

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

string

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

聯集欄位 _query。

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

string

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

各類別支援的運算子：

寄件者和收件者：

  • from:<email>：由特定使用者傳送。
  • to:<email>：傳送給特定使用者。
  • cc:<email> - 副本中的特定使用者。
  • bcc:<email> - 密件副本中的特定使用者。
  • deliveredto:<email>：已送達特定地址。
  • list:<email>：來自特定郵寄清單。

時間和日期：

  • after:YYYY/MM/DD / newer:YYYY/MM/DD - 在某個日期之後收到。
  • before:YYYY/MM/DD / older:YYYY/MM/DD：在某個日期前收到。
  • older_than:<duration> - 較舊的期限 (例如 1y、2d)。
  • newer_than:<duration>：比某段時間更新。

內容：

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

標籤和類別：

  • label:<name>：特定標籤下的郵件。這項工具接受的是唱片公司 ID，而非顯示名稱。使用 list_labels 工具取得 ID。
  • category:<name> - 在類別中 (主要、社群網路、促銷內容、最新快訊、論壇、預訂、購物交易)。
  • in:<label>：在特定標籤 (封存、已延後、垃圾桶、已傳送、收件匣) 中搜尋。例如 in:trash、in:inbox。系統預設會納入已封存和已傳送的訊息，如要排除這些訊息，請使用 -in:archive 和 -in:sent。這項工具預設會明確排除草稿。使用 in:inbox 將搜尋範圍限制為收件匣。
  • has:userlabels - 含有任何使用者標籤。
  • has:nouserlabels - 沒有任何使用者標籤。
  • has:*-star：特定星號顏色 (如已啟用，例如 has:yellow-star)。
  • in:draft：搜尋草稿。-in:draft 表示從搜尋結果中排除草稿。
  • in:sent - 搜尋寄件備份中的郵件。
  • in:anywhere：在所有資料夾中搜尋 (包括垃圾郵件和垃圾桶)。

狀態：

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

大小：

  • size:<bytes>：以位元組為單位的特定大小。
  • larger:<size> / smaller:<size>：大於或小於某個大小 (例如 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。

聯集欄位 _view。

_view 只能是下列其中一項：
view

enum (ThreadView)

(選用步驟) 控制討論串清單中討論串的填入欄位。預設為 THREAD_VIEW_MINIMAL。THREAD_VIEW_MINIMAL 會傳回 id、snippet、subject、from、to、cc、date、labelIds。THREAD_VIEW_METADATA_ONLY 會傳回 id、from、to、cc、date、labelIds。

ThreadView

列舉，用於控管 ListThreads 和 SearchThreads 回應中討論串填入的欄位。

列舉
THREAD_VIEW_UNSPECIFIED 對應至 THREAD_VIEW_MINIMAL，以確保回溯相容性。
THREAD_VIEW_METADATA_ONLY 傳回 id、from、to、cc、date、labelIds。
THREAD_VIEW_MINIMAL 傳回 ID、摘要、主旨、寄件者、收件者、副本、日期、標籤 ID。

輸出內容的結構定義

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

SearchThreadsResponse

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

object (Thread)

對話串摘要清單。
nextPageToken

string

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

string (int64 format)

這項查詢的預估結果數。這項值應視為下限，舉例來說，如果值為 500，則系統可向使用者回報「500 以上」。

討論串

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
  ],
  "htmlBody": string,
  "attachments": [
    {
      object (AttachmentMetadata)
    }
  ],
  "labelIds": [
    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 時才會填入。
htmlBody

string

電子郵件的 HTML 內容，只有在 MessageFormat 為 FULL_CONTENT 時才會填入。
attachments[]

object (AttachmentMetadata)

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

string

附加至郵件的標籤 ID。包括使用者標籤和標準系統標籤的 ID，但僅限於 INBOX、SPAM、TRASH、UNREAD、STARRED、IMPORTANT、SENT、DRAFT、CHAT。

AttachmentMetadata

JSON 表示法 
{
  "id": string,
  "mimeType": string,
  "filename": string
}
欄位
id

string

僅供輸出。附件的 ID。
mimeType

string

附件的 MIME 類型。
filename

string

附件的檔案名稱。

工具註解

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

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://mail.google.com/
  • https://www.googleapis.com/auth/gmail.modify
  • https://www.googleapis.com/auth/gmail.readonly