MCP Tools Reference: chatmcp.googleapis.com

工具：search_messages

使用关键字和过滤条件搜索 Google Chat 消息，并以 Markdown 格式返回结果。适用于用户有权访问的所有聊天室，也可以限定在特定对话中。

在决定是使用 search_messages 还是其他搜索或阅读工具时，请遵循以下指南：

  • 当您要查找特定消息内容、关键字、提及、链接、发件人或未读消息时，请使用 search_messages，这些消息可能分布在多个聊天室中，或者没有已知的对话 ID。
  • 如果您知道特定的聊天室或会话串 ID，并且想要按时间顺序依次读取消息，请使用 list_messages。
  • 使用 search_conversations，按聊天室显示名称或参与者查找聊天室元数据（例如对话 ID），该命令仅搜索元数据，不搜索消息内容。

如果提供了 searchParameters，但未指定特定过滤条件，则会返回用户有权访问的所有对话中的近期消息。

以下代码示例展示了如何使用 curl 调用 search_messages MCP 工具。

Curl 请求 
curl --location 'https://chatmcp.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_messages",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

输入架构

SearchMessagesRequest

JSON 表示法 
{
  "searchParameters": {
    object (SearchParameters)
  },
  "pageSize": integer,
  "pageToken": string
}
字段
searchParameters

object (SearchParameters)

必需。搜索时要使用的搜索参数。
pageSize

integer

可选。返回的结果数上限（最多 100 个）。如果未指定，则最多返回 25 个。
pageToken

string

可选。从之前的 search_messages 调用接收的页面令牌。利用其进行后续页面检索。

SearchParameters

JSON 表示法 
{
  "keywords": [
    string
  ],
  "conversationId": string,
  "sender": string,
  "isUnread": boolean,
  "hasLink": boolean,
  "startTime": string,
  "endTime": string,
  "mentionsMe": boolean,
  "conversationIncludesUser": string,
  "spaceDisplayNames": [
    string
  ],
  "conversationTypes": [
    enum (ConversationType)
  ],
  "hasAttachment": boolean
}
字段
keywords[]

string

可选。一组用于过滤结果的关键字。
conversationId

string

可选。将搜索范围限定为特定对话标识符（由 search_conversations 工具返回）。格式：spaces/{ID}。
sender

string

可选。过滤来自特定用户的消息。您可以使用发件人的电子邮件地址或资源名称。用户资源名称的格式为 users/{ID}，其中 {ID} 可以是人员 ID 或其邮箱。
isUnread

boolean

可选。过滤出调用用户尚未阅读的消息。
hasLink

boolean

可选。过滤包含至少一个网址的消息。
startTime

string

可选。过滤在此时间之后创建的消息。格式：ISO 8601 时间戳。
endTime

string

可选。过滤在此时间之前创建的消息。格式：ISO 8601 时间戳。
mentionsMe

boolean

可选。过滤出明确提及调用用户的消息。
conversationIncludesUser

string

可选。过滤包含特定用户电子邮件地址或 ID 的私信和群聊中的消息。
spaceDisplayNames[]

string

可选。按聊天室名称列表过滤；聊天室显示名称部分匹配。注意：系统只会返回前 5 个匹配项。
conversationTypes[]

enum (ConversationType)

可选。按对话类型过滤。
hasAttachment

boolean

可选。过滤包含至少一个附件的邮件。注意：此字段正在开发中，可能尚未在所有环境中受支持。

ConversationType

定义对话类型。

枚举
CONVERSATION_TYPE_UNSPECIFIED 未指定。
NAMED_SPACE 已命名的聊天室。
GROUP_CHAT 3 人或更多人之间的群聊。
DIRECT_MESSAGE 两个人之间或一个人与一个 Chat 应用之间的私信。

输出架构

搜索 Google Chat 消息的响应。如果 next_page_token 已填充，则可以再次使用该令牌调用 SearchMessages，以检索下一页结果。

SearchMessagesResponse

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

object (ChatMessage)

符合搜索条件的消息对象列表。
nextPageToken

string

可作为 page_token 发送并用于检索下一页的令牌。如果省略此字段，则不存在后续页面。

ChatMessage

JSON 表示法 
{
  "messageId": string,
  "threadId": string,
  "plaintextBody": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "threadedReply": boolean,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "reactionSummaries": [
    {
      object (ReactionSummary)
    }
  ],
  "quotedMessageMetadata": {
    object (QuotedMessageMetadata)
  }
}
字段
messageId

string

消息的资源名称。格式：spaces/{space}/messages/{message}
threadId

string

此消息所属的会话。如果消息未归入消息串，则此字段为空。格式：spaces/{space}/threads/{thread}
plaintextBody

string

消息的正文，采用 Markdown 格式。
sender

object (User)

消息的发件人。
createTime

string

仅限输出。消息创建时的时间戳。格式：ISO 8601 时间戳。
threadedReply

boolean

消息是否为消息串回复。
attachments[]

object (ChatAttachmentMetadata)

邮件中包含的附件。
reactionSummaries[]

object (ReactionSummary)

消息中包含的表情符号回应摘要。
quotedMessageMetadata

object (QuotedMessageMetadata)

仅限输出。此邮件中引用或转发的原始邮件的相关信息。注意：此字段尚在开发中，可能尚未在所有环境中提供。

用户

JSON 表示法 
{
  "userId": string,
  "displayName": string,
  "email": string,
  "userType": enum (UserType)
}
字段
userId

string

Chat 用户的资源名称。格式：users/{user}。
displayName

string

Chat 用户的显示名称。
email

string

用户的邮箱。仅当用户类型为 HUMAN 时，系统才会填充此字段。
userType

enum (UserType)

用户类型。

ChatAttachmentMetadata

JSON 表示法 
{
  "attachmentId": string,
  "filename": string,
  "mimeType": string,
  "source": enum (Source),
  "driveFileId": string
}
字段
attachmentId

string

附件的资源名称。格式：spaces/{space}/messages/{message}/attachments/{attachment}。
filename

string

附件的名称。
mimeType

string

内容类型（MIME 类型）。
source

enum (Source)

附件的来源。
driveFileId

string

仅限输出。Google 云端硬盘文件的 ID。仅当来源为 DRIVE_FILE 时填充。与 Google 云端硬盘 MCP 搭配使用。

ReactionSummary

JSON 表示法 
{
  "emoji": string,
  "count": integer
}
字段
emoji

string

表情符号 Unicode 字符串或自定义表情符号名称。
count

integer

使用关联表情符号的回应总数。

QuotedMessageMetadata

JSON 表示法 
{
  "messageId": string,
  "lastUpdateTime": string,
  "quoteType": enum (QuoteType),
  "plaintextBody": string,
  "sender": string,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "forwardedMetadata": {
    object (ForwardedMetadata)
  }
}
字段
messageId

string

仅限输出。被引用或转发的原始消息的资源名称。格式：spaces/{space}/messages/{message}
lastUpdateTime

string

仅限输出。原始消息在被引用或转发之前创建或最后更新的时间戳。格式：ISO 8601 时间戳。
quoteType

enum (QuoteType)

仅限输出。报价类型。
plaintextBody

string

仅限输出。引用或转发时原始消息文本正文的快照。FORWARD 使用 Markdown 格式，REPLY 使用纯文本格式。
sender

string

仅限输出。原始消息的作者显示名称。
attachments[]

object (ChatAttachmentMetadata)

仅限输出。原始邮件中包含的附件。仅针对 FORWARD 报价类型填充。
forwardedMetadata

object (ForwardedMetadata)

仅限输出。有关转发消息的来源对话的元数据。仅针对 FORWARD 报价类型填充。

ForwardedMetadata

JSON 表示法 
{
  "conversationId": string,
  "conversationDisplayName": string
}
字段
conversationId

string

仅限输出。源对话的资源名称。格式：spaces/{space}
conversationDisplayName

string

仅限输出。转发消息时来源对话的显示名称。对于有名称的聊天室，此字段为聊天室名称。对于 1 对 1 私信，这是另一位参与者的姓名。对于未命名的群聊，系统会根据成员的名字生成一个名称。

UserType

Google Chat 用户的类型。

枚举
USER_TYPE_UNSPECIFIED 未指定。
HUMAN 人类用户。
APP 应用用户。

来源

附件的来源。

枚举
SOURCE_UNSPECIFIED Reserved.
DRIVE_FILE 该文件是 Google 云端硬盘文件。
UPLOADED_CONTENT 文件已上传到 Chat。

QuoteType

引用类型，用于指明消息是引用回复还是转发的消息。

枚举
QUOTE_TYPE_UNSPECIFIED Reserved. 未定义的报价类型。
REPLY 该消息是对同一消息串中原始消息的引用回复。
FORWARD 该消息是从其他对话中的原始消息转发而来，或从同一对话中的其他消息串转发而来。

工具注释

工具注解会发送到 MCP 客户端，用于描述给定工具的基本风险。大多数客户端会将这些提示视为不可信，但可用于决定何时向用户发送确认提示。

除了标题字符串之外，还定义了以下布尔值提示：

  • readOnlyHint：如果为 true，则该工具不会修改其环境。默认值：false。
  • destructiveHint：如果为 true，则该工具可以执行破坏性操作。如果为 false，则该工具只能执行添加操作。默认值：true。
  • idempotentHint：如果为 true，则使用相同参数重复调用该工具不会对其环境产生额外影响。默认值：false。
  • openWorldHint：如果为 true，则该工具可以与外部实体的“开放世界”进行交互。如果为 false，则该工具只能与内部实体交互。例如，网页搜索工具是开放世界，而记忆工具不是开放世界。

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

授权范围

需要以下 OAuth 范围之一：

  • https://www.googleapis.com/auth/chat.messages.readonly
  • https://www.googleapis.com/auth/chat.spaces.readonly
  • https://www.googleapis.com/auth/chat.memberships.readonly
  • https://www.googleapis.com/auth/chat.users.readstate.readonly