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、snippet、subject、from、to、cc、date、labelIds。

输出架构

针对 SearchThreads RPC 的响应消息。

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

线程的唯一标识符。
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

消息的唯一标识符。
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