MCP Tools Reference: chatmcp.googleapis.com

Tool: list_messages

Retrieves messages from a specified Google Chat conversation (Space, direct message (DM) or group DM) in Markdown format. Allows filtering by thread, time range, and number of messages. Additionally, the next page of messages can be retrieved to allow for more context. Private messages (messages only visible to a single user) are filtered out.

The following code sample shows how to use curl to call the list_messages MCP tool.

Curl Request 
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
}'

Input Schema

ListChatMessagesRequest

JSON representation 
{
  "conversationId": string,
  "threadId": string,
  "pageSize": integer,
  "pageToken": string,
  "startTime": string,
  "endTime": string
}
Fields
conversationId

string

Required. The ID of the conversation. A conversation can either be a space, direct message (DM) or group DM/Chat. Format: spaces/{space}
threadId

string

Optional. The ID of a specific thread within the conversation. If provided, only messages from this thread will be returned. If omitted, messages from all threads in the conversation are considered. Format: spaces/{space}/threads/{thread}
pageSize

integer

Optional. The maximum number of messages to return. The service may return fewer than this value. If unspecified, defaults to 20. The maximum value is 50. If you use a value more than 50, it's automatically changed to 50.
pageToken

string

Optional. A page token, received from a previous list_messages call. Provide this to retrieve the subsequent page.
startTime

string

Optional. ISO 8601 timestamp to filter messages. Only messages created after this time will be returned.
endTime

string

Optional. ISO 8601 timestamp to filter messages. Only messages created before this time will be returned.

Output Schema

Response containing the list of messages from the requested conversation.

ListChatMessagesResponse

JSON representation 
{
  "messages": [
    {
      object (ChatMessage)
    }
  ],
  "nextPageToken": string
}
Fields
messages[]

object (ChatMessage)

List of messages retrieved, in reverse chronological order (newest first).
nextPageToken

string

A token, which can be sent as page_token in a subsequent ListMessagesRequest to retrieve the next page of messages. If this field is empty, there are no more pages.

ChatMessage

JSON representation 
{
  "messageId": string,
  "threadId": string,
  "plaintextBody": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "threadedReply": boolean,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "reactionSummaries": [
    {
      object (ReactionSummary)
    }
  ]
}
Fields
messageId

string

Resource name of the message. Format: spaces/{space}/messages/{message}
threadId

string

The thread this message belongs to. This will be empty if the message is unthreaded. Format: spaces/{space}/threads/{thread}
plaintextBody

string

Text body of the message using Markdown formatting.
sender

object (User)

The sender of the message.
createTime

string

Output only. Timestamp when the message was created.
threadedReply

boolean

Whether message is a thread reply.
attachments[]

object (ChatAttachmentMetadata)

Attachments included in the message.
reactionSummaries[]

object (ReactionSummary)

The emoji reactions summary included in the message.

User

JSON representation 
{
  "userId": string,
  "displayName": string,
  "email": string,
  "userType": enum (UserType)
}
Fields
userId

string

Resource name of a Chat user. Format: users/{user}.
displayName

string

The display name of a Chat user.
email

string

The email address of the user. This field is only populated when the user type is HUMAN.
userType

enum (UserType)

The type of the user.

ChatAttachmentMetadata

JSON representation 
{
  "attachmentId": string,
  "filename": string,
  "mimeType": string,
  "source": enum (Source)
}
Fields
attachmentId

string

Resource name of the attachment. Format: spaces/{space}/messages/{message}/attachments/{attachment}.
filename

string

Name of the attachment.
mimeType

string

Content type (MIME type).
source

enum (Source)

The source of the attachment.

ReactionSummary

JSON representation 
{
  "emoji": string,
  "count": integer
}
Fields
emoji

string

The emoji unicode string or custom emoji name.
count

integer

The total number of reactions using the associated emoji.

UserType

The type of a Google Chat user.

Enums
USER_TYPE_UNSPECIFIED Unspecified.
HUMAN Human user.
APP App user.

Source

The source of the attachment.

Enums
SOURCE_UNSPECIFIED Reserved.
DRIVE_FILE The file is a Google Drive file.
UPLOADED_CONTENT The file is uploaded to Chat.

Tool Annotations

Tool annotations are sent to MCP clients to describe the basic risk of a given tool. Most clients treat these hints as untrusted, but they can be used to decide when a confirmation prompt might be sent to a user.

Along with the title string, the following boolean hints are defined as follows:

  • readOnlyHint: If true, the tool doesn't modify its environment. Default: false.
  • destructiveHint: If true, then the tool can perform destructive actions. If false, then the tool can only perform additive actions. Default: true.
  • idempotentHint: If true, then calling the tool repeatedly with the same arguments will have no additional effect on its environment. Default: false.
  • openWorldHint: If true, then the tool can interact with an 'open world' of external entities. If false, then the tool can only interact with internal entities. For example, a web search tool would be open world, while a memory tool would not be open world.

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌

Authorization Scopes

Requires one of the following OAuth scopes:

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