MCP Tools Reference: gmailmcp.googleapis.com

工具：search_threads

列出经过身份验证的用户的 Gmail 账号中的电子邮件会话。

此工具可以根据查询字符串过滤线程，并支持分页。它会返回一个线程列表，其中包括线程 ID 和相关消息。每条相关消息都包含详细信息，例如邮件正文的摘要、主题、发件人、收件人等。请注意，此工具不会返回完整的邮件正文；如果需要，请使用“get_thread”工具并提供相应线程 ID 来获取完整的邮件正文。

以下示例演示了如何使用 curl 调用 search_threads MCP 工具。

Curl 请求 
curl --location 'https://gmailmcp.googleapis.com/mcp' \
--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 MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

输入架构

针对 SearchThreads RPC 的请求消息。

SearchThreadsRequest

JSON 表示法 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean
}
字段

联合字段 _page_size。

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

integer

可选。要返回的最大线程数。如果未指定，则默认为 20。允许的最大值为 50。

联合字段 _page_token。

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

string

可选。用于检索列表中特定结果页面的分页令牌。留空可提取第一页。

联合字段 _query。

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

string

可选。用于过滤线程的查询字符串，格式与 Gmail 搜索栏相同。如果省略，则会列出所有会话（默认情况下不包括垃圾内容和已删除内容）。关键运算符：from: - 来自特定发件人的消息。to: - 发送给特定收件人的消息。subject: - 主题中包含特定字词的邮件。 - 正文或主题中包含特定字词的邮件。is:unread - 未读邮件。is:starred - 已加星标的邮件。has:attachment - 包含附件的邮件。after:YYYY/MM/DD - 在某个日期之后发送的消息。before:YYYY/MM/DD - 在指定日期之前发送的邮件。newer_than:

 Examples:
 "subject:OneMCP Update"
 "from:gduser1@workspacesamples.dev"
 "to:gduser2@workspacesamples.dev AND newer_than:7d"
 "project proposal has:attachment"
 "is:unread"

联合字段 _include_trash。

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

boolean

可选。在结果中包含回收站中的草稿。默认值为 false。

输出架构

针对 SearchThreads RPC 的响应消息。

SearchThreadsResponse

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

object (Thread)

线程摘要列表。
nextPageToken

string

可在后续调用中用于检索下一页帖子的令牌。仅当有更多结果时才会显示。

会话

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

string

线程的唯一标识符。
messages[]

object (Message)

相应线程中的消息列表，按时间顺序排序。

消息

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

string

消息的唯一标识符。
snippet

string

消息正文的简短内容。
subject

string

从标头中提取的邮件主题：
sender

string

发件人的电子邮件地址。
toRecipients[]

string

收件人电子邮件地址。
ccRecipients[]

string

抄送收件人的电子邮件地址。
date

string

消息的日期，采用 ISO 8601 格式 (YYYY-MM-DD)。
plaintextBody

string

完整正文内容，仅在 MessageFormat 为 FULL_CONTENT 时填充。

工具注释

破坏性提示：❌ | 等幂性提示：✅ | 只读提示：✅ | 开放世界提示：❌