MCP Tools Reference: chatmcp.googleapis.com

Tool: search_messages

Searches for Google Chat messages using keywords and filters returning them in Markdown format. Works across all spaces the user has access to, or can be scoped to a specific conversation.

Follow this guidance when deciding to use search_messages vs other search or read tools:

  • Use search_messages when looking for specific message content, keywords, mentions, links, senders or unread messages potentially across multiple spaces or without a known conversation ID.
  • Use list_messages when you know the specific space or thread ID and want to read messages sequentially in chronological order.
  • Use search_conversations to find space metadata such as conversation IDs by space display name or participants (it searches metadata only, not message contents).

If searchParameters is provided without specific filters, recent messages across conversations accessible to the user are returned.

The following code sample shows how to use curl to call the search_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": "search_messages",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

SearchMessagesRequest

JSON representation 
{
  "searchParameters": {
    object (SearchParameters)
  },
  "pageSize": integer,
  "pageToken": string
}
Fields
searchParameters

object (SearchParameters)

Required. The search parameters to use for the search.
pageSize

integer

Optional. The maximum number of results to return (max up to 100). If unspecified, at most 25 are returned.
pageToken

string

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

SearchParameters

JSON representation 
{
  "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
}
Fields
keywords[]

string

Optional. A set of keywords which are used to filter the results.
conversationId

string

Optional. Scopes the search to a specific conversation identifier, as returned from the search_conversations tool. Format: spaces/{ID}.
sender

string

Optional. Filter for messages from a specific user. Either the email or resource name of the sender can be used. User resource names are formatted as users/{ID}, where {ID} can be a person ID or their email address.
isUnread

boolean

Optional. Filter for messages that have not been read by the calling user.
hasLink

boolean

Optional. Filter for messages containing at least one URL.
startTime

string

Optional. Filter for messages created after this time. Format: ISO 8601 timestamp.
endTime

string

Optional. Filter for messages created before this time. Format: ISO 8601 timestamp.
mentionsMe

boolean

Optional. Filter for messages that explicitly mention the calling user.
conversationIncludesUser

string

Optional. Filter for messages in DMs and group chats that include the specific user email or ID.
spaceDisplayNames[]

string

Optional. Filter by a list of space names; space display names are partially matched. Note: Only the top 5 matches are returned.
conversationTypes[]

enum (ConversationType)

Optional. Filter by the type of conversation.
hasAttachment

boolean

Optional. Filter for messages containing at least one attachment. Note: This field is under development and may not be supported in all environments yet.

ConversationType

Defines the type of conversation.

Enums
CONVERSATION_TYPE_UNSPECIFIED Unspecified.
NAMED_SPACE A named space.
GROUP_CHAT A group chat between 3 or more people.
DIRECT_MESSAGE A direct message between two humans, or a human and a Chat app.

Output Schema

Response to search for Google Chat messages. If next_page_token is populated, call SearchMessages can be called again with that token to retrieve the next page of results.

SearchMessagesResponse

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

object (ChatMessage)

List of message objects that match the search criteria.
nextPageToken

string

A token that can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.

ChatMessage

JSON representation 
{
  "messageId": string,
  "threadId": string,
  "plaintextBody": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "threadedReply": boolean,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "reactionSummaries": [
    {
      object (ReactionSummary)
    }
  ],
  "quotedMessageMetadata": {
    object (QuotedMessageMetadata)
  }
}
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. Format: ISO 8601 timestamp.
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.
quotedMessageMetadata

object (QuotedMessageMetadata)

Output only. Information about an original message that is quoted or forwarded in this message. Note: This field is under development and may not be present in all environments yet.

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),
  "driveFileId": string
}
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.
driveFileId

string

Output only. The ID for the Google Drive file. Only populated when the source is DRIVE_FILE. Use with the Google Drive MCP.

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.

QuotedMessageMetadata

JSON representation 
{
  "messageId": string,
  "lastUpdateTime": string,
  "quoteType": enum (QuoteType),
  "plaintextBody": string,
  "sender": string,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "forwardedMetadata": {
    object (ForwardedMetadata)
  }
}
Fields
messageId

string

Output only. Resource name of the original message that is quoted or forwarded. Format: spaces/{space}/messages/{message}
lastUpdateTime

string

Output only. Timestamp when the original message was created or last updated prior to being quoted or forwarded. Format: ISO 8601 timestamp.
quoteType

enum (QuoteType)

Output only. The type of quote.
plaintextBody

string

Output only. Snapshot of the text body of the original message at the time of quoting or forwarding. Formatted using Markdown for FORWARD, and plain text for REPLY.
sender

string

Output only. The author display name of the original message.
attachments[]

object (ChatAttachmentMetadata)

Output only. Attachments that were part of the original message. Populated only for the FORWARD quote type.
forwardedMetadata

object (ForwardedMetadata)

Output only. Metadata about the source conversation of the forwarded message. Populated only for the FORWARD quote type.

ForwardedMetadata

JSON representation 
{
  "conversationId": string,
  "conversationDisplayName": string
}
Fields
conversationId

string

Output only. The resource name of the source conversation. Format: spaces/{space}
conversationDisplayName

string

Output only. The display name of the source conversation at the time the message was forwarded. For named spaces, this is the space name. For 1:1 direct messages, this is the other participant's name. For unnamed group chats, this is a generated name based on members' names.

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.

QuoteType

The quote type indicating whether the message is a quote reply or a forwarded message.

Enums
QUOTE_TYPE_UNSPECIFIED Reserved. Undefined quote type.
REPLY The message is a quote reply to an original message in the same thread.
FORWARD The message is forwarded from an original message in a different conversation, or from a different thread in the same conversation.

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.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