MCP Tools Reference: gmailmcp.googleapis.com

工具：search_threads

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

此工具可以根据查询字符串过滤会话，并支持分页。它会返回会话列表，包括会话 ID 和相关消息。每条相关消息都包含详细信息，例如消息正文的摘要、主题、发件人、收件人等。请注意，此工具不会返回完整消息正文；如果需要，请使用带有会话 ID 的“get_thread”工具来提取完整消息正文。符合排除条件的会话可能仍会显示在结果中。这是因为 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 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

可选。用于检索列表中特定结果页面的页令牌。留空可提取第一页。此字段主要用于分页，以便从上一次 SearchThreads 调用停止的位置继续提取结果，尤其是在与查询匹配的会话数超过 page_size 限制时。

联合字段 _query。

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

string

可选。用于过滤会话的查询字符串。自然语言查询必须先转换为 Gmail 语法查询，才能使用此工具。如果省略，系统会列出所有会话（默认排除垃圾邮件和已删除邮件）。

按类别划分的支持的运算符：

发件人和收件人：from: - 由特定人员发送。to: - 发送给特定人员。cc: - 抄送给特定人员。bcc: - 密送给特定人员。deliveredto: - 发送至特定地址。list: - 来自特定邮寄名单。

时间和日期：after:YYYY/MM/DD / newer:YYYY/MM/DD - 在某个日期之后收到。before:YYYY/MM/DD / older:YYYY/MM/DD - 在某个日期之前收到。 older_than: - 比某个时长更早（例如 1y、2d）。newer_than: - 比某个时长更晚。

内容：subject: - 主题行中的字词。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 RPC 的响应消息。

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

会话的唯一标识符。
messages[]

object (Message)

会话中的消息列表，按时间顺序排序。

消息

JSON 表示法 
{
  "id": string,
  "snippet": string,
  "subject": string,
  "sender": string,
  "toRecipients": [
    string
  ],
  "ccRecipients": [
    string
  ],
  "date": string,
  "plaintextBody": string,
  "attachmentIds": [
    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 时才会填充。
attachmentIds[]

string

仅限输出。附件 ID，仅当 MessageFormat 为 FULL_CONTENT 时才会填充。

工具注释

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