MCP Tools Reference: chatmcp.googleapis.com

工具：list_messages

以 Markdown 格式从指定的 Google Chat 对话（聊天室、私信 (DM) 或群聊 DM）检索消息。支持按会话、时间范围和消息数量进行过滤。此外，还可以检索下一页消息，以便了解更多上下文。系统会过滤掉私信（仅对单个用户可见的消息）。

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

输入架构

ListChatMessagesRequest

JSON 表示法 
{
  "conversationId": string,
  "threadId": string,
  "pageSize": integer,
  "pageToken": string,
  "startTime": string,
  "endTime": string
}
字段
conversationId

string

必需。对话的 ID。对话可以是聊天室、私信 (DM) 或群聊 DM/Chat。格式：spaces/{space}
threadId

string

可选。对话中特定会话的 ID。如果提供此 ID，则仅返回此会话中的消息。如果省略此 ID，则会考虑对话中所有会话中的消息。格式：spaces/{space}/threads/{thread}
pageSize

integer

可选。要返回的消息数量上限。服务返回的值可能小于此值。如果未指定，则默认为 20。最大值为 50。如果您使用的值超过 50，系统会自动将其更改为 50。
pageToken

string

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

string

可选。用于过滤消息的 ISO 8601 时间戳。系统只会返回在此时间之后创建的消息。
endTime

string

可选。用于过滤消息的 ISO 8601 时间戳。系统只会返回在此时间之前创建的消息。

输出架构

包含所请求对话中的消息列表的响应。

ListChatMessagesResponse

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

object (ChatMessage)

检索到的消息列表，按时间逆序排列（由新到旧）。
nextPageToken

string

一个令牌，可在后续 ListMessagesRequest 中作为 page_token 发送，以检索下一页消息。如果此字段为空，则表示没有更多页面。

ChatMessage

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

string

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

string

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

string

使用 Markdown 格式的消息正文。
sender

object (User)

消息的发件人。
createTime

string

仅限输出。消息创建时的时间戳。
threadedReply

boolean

消息是否为会话回复。
attachments[]

object (ChatAttachmentMetadata)

消息中包含的附件。
reactionSummaries[]

object (ReactionSummary)

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

用户

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)
}
字段
attachmentId

string

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

string

附件的名称。
mimeType

string

内容类型 (MIME 类型)。
source

enum (Source)

附件的来源。

ReactionSummary

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

string

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

integer

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

UserType

Google Chat 用户的类型。

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

来源

附件的来源。

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

工具注释

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

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

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

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

授权范围

需要以下 OAuth 范围之一：

  • https://www.googleapis.com/auth/chat.messages
  • https://www.googleapis.com/auth/chat.messages.readonly