MCP Tools Reference: chatmcp.googleapis.com

工具：send_message

向话题发送一条采用 Markdown 格式的 Google Chat 聊天消息。

此工具使用对话 ID、可选的会话串 ID 和消息文本作为输入。

您可以使用 search_conversations 工具查找对话 ID。

它会返回创建的消息。

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

输入架构

SendMessageRequest

JSON 表示法 
{
  "conversationId": string,
  "threadId": string,
  "messageText": string,
  "cards": [
    {
      object
    }
  ],
  "inlineCitations": [
    {
      object (Citation)
    }
  ],
  "footerCitedSources": [
    {
      object (CitedSource)
    }
  ]
}
字段
conversationId

string

必需。要向其发送消息的对话的 ID（例如“spaces/AAAA…”）。
threadId

string

可选。要将消息发送到的会话串的 ID（例如“spaces/AAAA…/threads/BBBB…”）。如果未设置，消息将发送到新会话。
messageText

string

必需。消息的主要内容。您可以使用标准 Markdown 添加格式（请注意，不支持表格）。支持以下格式：

  • 粗体： **text**
  • 斜体： *text* 或 _text_
  • 删除线： ~~text~~
  • 等宽字体： text
  • 等宽字体块：
```
line 1
line 2
```
  • 项目符号列表：
* item 1
* item 2
  • 有序列表：
1. item 1
2. item 2
  • 块引用： > quoted text
  • 超链接： [label](url)
  • 提及用户：使用自闭合 HTML 标记 chat-user，并添加属性 data-email="user@example.com" 或 data-user="users/USER_ID"。如果已知，则首选具有 USER_ID 的 data-user 属性，否则回退到具有用户电子邮件地址的 data-email 属性。如果您使用 data-user 属性，请务必添加在其他工具返回值中看到的 users/ 前缀。注意：每条消息最多可提及 10 人。严禁提及所有用户（例如，使用 @all 或带有 users/all 的 HTML 标记）。
  • 自定义表情符号：使用自闭合 HTML 标记 chat-emoji，并添加属性 data-custom-emoji="customEmojis/abc" 或 data-emoji-name=":xyz:"。
  • 引用：将引用的文本封装在 HTML 标记 chat-citation 中，并使用与引用 ID 匹配的 data-id 属性。如果 chat-citation 标记的 data-id 与任何 Citation.id 都不匹配，则系统会忽略该标记，并将封装的文本呈现为纯文本。注意：每条消息最多可包含 20 个内嵌引用。
cards[]

object (Struct format)

可选。附加到消息的卡片。每张卡的大小上限为 32 KB。每张卡片都表示为遵循 Google Chat 卡片格式（Google Workspace UIKit 卡片/卡片 v2）的 JSON 结构体。如需将卡片附加到消息，Chat 应用必须是聊天室的成员。

卡片标识：

  • 每张卡片中的顶级 name 字符串字段用作其标识符。
  • 如果一条消息附加了多张卡片，则每张卡片都必须指定一个唯一的非空 name。
inlineCitations[]

object (Citation)

可选。通过 chat-citation 标记在 message_text 中引用的内嵌引用。每条消息最多可包含 20 个内嵌引用。未引用的内嵌引用（即 message_text 中没有匹配的 chat-citation 标记的引用）会被忽略，不会导致验证错误。
footerCitedSources[]

object (CitedSource)

可选。在消息底部（页脚）以参考卡片的形式显示顶级引用来源。一条消息中的所有内嵌引用和消息底部参考来源总共最多可包含 50 个引用来源。

结构体

JSON 表示法 
{
  "fields": {
    string: value,
    ...
  }
}
字段
fields

map (key: string, value: value (Value format))

动态类型值的无序映射。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

FieldsEntry

JSON 表示法 
{
  "key": string,
  "value": value
}
字段
key

string
value

value (Value format)

值

JSON 表示法 
{

  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
}
字段
联合字段 kind。值的类型。kind 只能是下列其中一项：
nullValue

null

表示 JSON null。
numberValue

number

表示 JSON 数字。不得为 NaN、Infinity 或 -Infinity，因为 JSON 不支持这些值。这也无法表示较大的 Int64 值，因为 JSON 格式通常不支持在其数字类型中使用这些值。
stringValue

string

表示 JSON 字符串。
boolValue

boolean

表示 JSON 布尔值（JSON 中的 true 或 false 字面量）。
structValue

object (Struct format)

表示一个 JSON 对象。
listValue

array (ListValue format)

表示 JSON 数组。

ListValue

JSON 表示法 
{
  "values": [
    value
  ]
}
字段
values[]

value (Value format)

动态类型值的重复字段。

引用

JSON 表示法 
{
  "id": string,
  "citedSources": [
    {
      object (CitedSource)
    }
  ]
}
字段
id

string

必需。与 message_text 中 chat-citation 标记内的 data-id 属性匹配的唯一标识符（例如，使用 chat-citation 和属性 data-id="ID" 封装引用的文本）。只能包含 ASCII 字母、数字、下划线或连字符（1-63 个字符）。在消息中的所有引用中必须是唯一的。
citedSources[]

object (CitedSource)

必需。此引用悬停卡片附带一个或多个来源。一条消息中的所有内嵌引用和消息底部参考来源总共最多可包含 50 个引用来源。

CitedSource

JSON 表示法 
{
  "title": string,
  "url": string,
  "snippet": string,
  "imageUrl": string,
  "footer": string
}
字段
title

string

必需。来源的纯文本标题（例如“Google Workspace 开发者预览版计划”）。标题不支持 Markdown 格式。
url

string

必需。所引用资源的网址（必须是有效的 http:// 或 https:// 网址，例如“https://developers.google.com/workspace/preview”）。
snippet

string

可选。直接来自来源的简短摘录或摘要。显示在悬停卡片或页脚中。仅限纯文本。长度上限为 1,000 个字符。
imageUrl

string

可选。图片预览缩略图的网址（必须使用 https:// 网址）。
footer

string

可选。卡片页脚中显示的附加提供方文字（例如域名“developers.google.com”或作者/组织名称）。

NullValue

表示 JSON null。

NullValue 是一个哨兵，使用仅有一个值的枚举来表示 Value 类型联合的 null 值。

如果 NullValue 类型的字段具有 0 以外的任何值，则会被视为无效。大多数 ProtoJSON 序列化器都会发出一个 Value，其中 null_value 设置为 JSON null，而不管整数值如何，因此会往返于 0 值。

枚举
NULL_VALUE Null 值。

输出架构

向 Google Chat 对话发送消息的响应。

SendMessageResponse

JSON 表示法 
{
  "message": {
    object (ChatMessage)
  }
}
字段
message

object (ChatMessage)

已发送的消息。

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
  • https://www.googleapis.com/auth/chat.messages.create