MCP Tools Reference: gmailmcp.googleapis.com

工具：list_drafts

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

此工具可以根据查询字符串过滤草稿，并支持分页。它会返回草稿列表，包括草稿的 ID 和主题（除非 view 设置为 DRAFT_VIEW_METADATA_ONLY）。page_token 可用于对结果进行分页。如需检索后续结果页面，请使用上一个响应中返回的 page_token。

view 参数用于控制在响应中填充哪些字段。默认情况下（或使用 DRAFT_VIEW_FULL 时），它会返回完整内容。使用 DRAFT_VIEW_METADATA_ONLY 排除敏感内容，例如主题和正文。

以下示例演示了如何使用 curl 调用 list_drafts 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": "list_drafts",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

输入架构

针对 ListDrafts RPC 的请求消息。

ListDraftsRequest

JSON 表示法 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "view": enum (DraftView)
}
字段

联合字段 _page_size。

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

integer

可选。要返回的草稿数量上限。如果未指定，则默认为 20。允许的最大值为 50。

联合字段 _page_token。

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

string

可选。从上一次 list_drafts 调用中收到的令牌，用于检索下一页结果。留空可提取第一页。此参数主要用于分页，以便从上一次 ListDraft 调用停止的位置继续提取结果，尤其是在与查询匹配的草稿数量超过 page_size 限制时。

联合字段 _query。

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

string

示例：

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

使用空格或短划线 (-) 可将数字分隔开来，而使用点 (.) 可表示小数。例如，01.2047-100 会被视为两个数字：01.2047 和 100。

注意：如果我们想确保返回查询的所有草稿，可以对结果进行分页，方法是反复调用该工具，直到响应包含一个空的草稿列表。

联合字段 _view。

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

enum (DraftView)

可选。控制草稿列表中为草稿填充的字段。默认情况下（或使用 DRAFT_VIEW_FULL 时），它会返回完整内容，其中包含草稿 ID、threadID、收件人、抄送、密送、日期、主题和正文。使用 DRAFT_VIEW_METADATA_ONLY 可排除主题和正文。

DraftView

用于控制 ListDrafts 响应中填充的草稿字段的枚举。

枚举
DRAFT_VIEW_UNSPECIFIED 映射到 DRAFT_VIEW_FULL 以实现向后兼容性。
DRAFT_VIEW_METADATA_ONLY 仅元数据：不包括主题、plaintext_body、html_body。
DRAFT_VIEW_FULL 元数据 + UGC（默认行为）。

输出架构

针对 ListDrafts RPC 的响应消息。

ListDraftsResponse

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

object (Draft)

草稿列表。
nextPageToken

string

可在后续调用中用于检索下一页草稿的令牌。如果与查询匹配的草稿数量超过了 page_size 限制，响应将包含 next_page_token。如需检索下一页结果，请在下一个 ListDraftsRequest 的 page_token 字段中传递此令牌。

草稿

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

string

草稿资源的唯一标识符。
subject

string

草稿邮件的主题行。
threadId

string

相应草稿所属的线程的 ID。
toRecipients[]

string

从标头中提取的“收件人”电子邮件地址列表。
ccRecipients[]

string

从标头中提取的“抄送”收件人电子邮件地址列表。
bccRecipients[]

string

从标头中提取的“密送”收件人电子邮件地址列表。
plaintextBody

string

纯文本正文内容（如有）。
date

string

草稿的日期，采用 ISO 8601 格式 (YYYY-MM-DD)。
htmlBody

string

相应草稿的 HTML 正文内容（如果有）。

工具注释

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

授权范围

需要以下 OAuth 范围之一：

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