MCP Tools Reference: gmailmcp.googleapis.com

工具：get_message

通过经过身份验证的用户的 Gmail 账号中的特定电子邮件的唯一邮件 ID 来检索该邮件。

如果您已知道某封电子邮件的邮件 ID，可以使用此工具检查该电子邮件。如果用户想要详细阅读特定电子邮件、检查邮件的确切措辞，或检查单封电子邮件的附件元数据，那么此工具非常适合。不适合检索整个对话或查看来回讨论串；请改用“get_thread”工具。关键指标包括：用户是否要求获取之前搜索返回的特定邮件 ID 的完整内容，或者查询是否要求检查特定个人电子邮件而不是整个对话串。用户提示示例：“获取消息 ID 为 18f123456789abcd 的消息的完整文本。”“Read the latest message in that thread from Alice.”（朗读 Alice 在相应对话串中发送的最新消息）和“What are the attachment names in the email I just received from HR?”（我刚刚收到的那封来自人力资源部门的电子邮件中包含哪些附件名称？）

可选的 messageFormat 参数用于控制返回的消息的格式。默认情况下（或使用 FULL_CONTENT 时），它会返回消息的完整内容。使用 MINIMAL 仅包含主题和摘要（不包含正文）。使用 METADATA_ONLY 可以仅包含基本元数据（消息 ID、线程 ID、标签、时间戳和大小估计值）。

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

输入架构

针对 GetMessage RPC 的请求消息。

GetMessageRequest

JSON 表示法 
{
  "messageId": string,
  "messageFormat": enum (MessageFormat)
}
字段
messageId

string

必需。要提取的消息的唯一标识符。
messageFormat

enum (MessageFormat)

可选。指定返回的消息的格式。默认值为 FULL_CONTENT。

MessageFormat

用于控制线程中消息的详细程度的枚举。

枚举
MESSAGE_FORMAT_UNSPECIFIED 默认值为 FULL_CONTENT。
MINIMAL 返回邮件摘要和关键标头（主题、发件人、收件人、抄送、日期）。
FULL_CONTENT 返回“MINIMAL”中的所有信息，以及每封邮件的完整正文内容。
METADATA_ONLY 仅限元数据：不包括主题、摘要、正文、附件文件名。

输出架构

消息串中的消息。

消息

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
  • https://www.googleapis.com/auth/gmail.metadata