MCP Tools Reference: chatmcp.googleapis.com

Tool: search_messages

Sucht mithilfe von Suchbegriffen und Filtern nach Google Chat-Nachrichten und gibt sie im Markdown-Format zurück. Funktioniert in allen Gruppenbereichen, auf die der Nutzer Zugriff hat, oder kann auf eine bestimmte Unterhaltung beschränkt werden.

Beachten Sie die folgenden Hinweise, wenn Sie sich für die Verwendung von search_messages im Vergleich zu anderen Such- oder Lesetools entscheiden:

  • Verwenden Sie search_messages, wenn Sie nach bestimmten Nachrichteninhalten, Keywords, Erwähnungen, Links, Absendern oder ungelesenen Nachrichten suchen, die sich möglicherweise in mehreren Gruppenbereichen befinden oder keine bekannte Unterhaltungs-ID haben.
  • Verwenden Sie list_messages, wenn Sie die ID des Gruppenbereichs oder Threads kennen und Nachrichten sequenziell in chronologischer Reihenfolge lesen möchten.
  • Mit search_conversations können Sie Metadaten von Gruppenbereichen wie Unterhaltungs-IDs anhand des Anzeigenamens des Gruppenbereichs oder der Teilnehmer finden. Dabei werden nur Metadaten durchsucht, nicht der Inhalt von Nachrichten.

Wenn searchParameters ohne bestimmte Filter angegeben wird, werden die letzten Nachrichten aus allen Unterhaltungen zurückgegeben, auf die der Nutzer Zugriff hat.

Das folgende Codebeispiel zeigt, wie Sie mit curl das MCP-Tool search_messages aufrufen.

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

Eingabeschema

SearchMessagesRequest

JSON-Darstellung 
{
  "searchParameters": {
    object (SearchParameters)
  },
  "pageSize": integer,
  "pageToken": string
}
Felder
searchParameters

object (SearchParameters)

Erforderlich. Die Suchparameter, die für die Suche verwendet werden sollen.
pageSize

integer

Optional. Die maximale Anzahl der zurückzugebenden Ergebnisse (maximal 100). Wenn nicht angegeben, werden maximal 25 zurückgegeben.
pageToken

string

Optional. Ein Seitentoken, das von einem vorherigen search_messages-Aufruf empfangen wurde. Geben Sie dieses an, um die nachfolgende Seite abzurufen.

SearchParameters

JSON-Darstellung 
{
  "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
}
Felder
keywords[]

string

Optional. Eine Reihe von Keywords, mit denen die Ergebnisse gefiltert werden.
conversationId

string

Optional. Beschränkt die Suche auf eine bestimmte Unterhaltungs-ID, die vom Tool „search_conversations“ zurückgegeben wird. Format: spaces/{ID}.
sender

string

Optional. Nachrichten von einem bestimmten Nutzer herausfiltern Es kann entweder die E-Mail-Adresse oder der Ressourcenname des Absenders verwendet werden. Nutzernamen werden als users/{ID} formatiert, wobei {ID} eine Personen-ID oder die E-Mail-Adresse sein kann.
isUnread

boolean

Optional. Filtern Sie nach Nachrichten, die vom aufrufenden Nutzer nicht gelesen wurden.
hasLink

boolean

Optional. Nachrichten filtern, die mindestens eine URL enthalten.
startTime

string

Optional. Nach Nachrichten filtern, die nach diesem Zeitpunkt erstellt wurden. Format: ISO 8601-Zeitstempel.
endTime

string

Optional. Nachrichten filtern, die vor diesem Zeitpunkt erstellt wurden. Format: ISO 8601-Zeitstempel.
mentionsMe

boolean

Optional. Nachrichten filtern, in denen der aufrufende Nutzer explizit erwähnt wird.
conversationIncludesUser

string

Optional. Nachrichten in Direktnachrichten und Gruppenchats filtern, die die E-Mail-Adresse oder ID des bestimmten Nutzers enthalten.
spaceDisplayNames[]

string

Optional. Nach einer Liste von Gruppenbereichsnamen filtern. Die Anzeigenamen von Gruppenbereichen werden teilweise abgeglichen. Hinweis: Es werden nur die fünf besten Übereinstimmungen zurückgegeben.
conversationTypes[]

enum (ConversationType)

Optional. Nach Unterhaltungstyp filtern
hasAttachment

boolean

Optional. Nachrichten mit mindestens einem Anhang filtern. Hinweis: Dieses Feld befindet sich noch in der Entwicklung und wird möglicherweise noch nicht in allen Umgebungen unterstützt.

ConversationType

Definiert den Typ der Unterhaltung.

Enums
CONVERSATION_TYPE_UNSPECIFIED Nicht angegeben
NAMED_SPACE Ein benannter Gruppenbereich.
GROUP_CHAT Ein Gruppenchat mit mindestens drei Personen.
DIRECT_MESSAGE Eine Direktnachricht zwischen zwei Personen oder einer Person und einer Chat-App.

Ausgabeschema

Antwort auf die Suche nach Google Chat-Nachrichten. Wenn „next_page_token“ ausgefüllt ist, kann „SearchMessages“ noch einmal mit diesem Token aufgerufen werden, um die nächste Ergebnisseite abzurufen.

SearchMessagesResponse

JSON-Darstellung 
{
  "messages": [
    {
      object (ChatMessage)
    }
  ],
  "nextPageToken": string
}
Felder
messages[]

object (ChatMessage)

Liste der Nachrichtenobjekte, die den Suchkriterien entsprechen.
nextPageToken

string

Ein Token, das als page_token gesendet werden kann, um die nächste Seite abzurufen. Wenn dieses Feld weggelassen wird, gibt es keine nachfolgenden Seiten.

ChatMessage

JSON-Darstellung 
{
  "messageId": string,
  "threadId": string,
  "plaintextBody": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "threadedReply": boolean,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "reactionSummaries": [
    {
      object (ReactionSummary)
    }
  ],
  "quotedMessageMetadata": {
    object (QuotedMessageMetadata)
  }
}
Felder
messageId

string

Ressourcenname der Nachricht. Format: spaces/{space}/messages/{message}
threadId

string

Der Thread, zu dem diese Nachricht gehört. Dieses Feld ist leer, wenn die Nachricht nicht Teil eines Threads ist. Format: spaces/{space}/threads/{thread}
plaintextBody

string

Textkörper der Nachricht im Markdown-Format.
sender

object (User)

Der Absender der Nachricht.
createTime

string

Nur Ausgabe. Zeitstempel für die Erstellung der Nachricht. Format: ISO 8601-Zeitstempel.
threadedReply

boolean

Gibt an, ob die Nachricht eine Antwort in einem Thread ist.
attachments[]

object (ChatAttachmentMetadata)

Anhänge, die in der Nachricht enthalten sind.
reactionSummaries[]

object (ReactionSummary)

Die Zusammenfassung der Emoji-Reaktionen, die in der Nachricht enthalten ist.
quotedMessageMetadata

object (QuotedMessageMetadata)

Nur Ausgabe. Informationen zu einer ursprünglichen Nachricht, die in dieser Nachricht zitiert oder weitergeleitet wird. Hinweis: Dieses Feld befindet sich noch in der Entwicklung und ist möglicherweise noch nicht in allen Umgebungen vorhanden.

Nutzer

JSON-Darstellung 
{
  "userId": string,
  "displayName": string,
  "email": string,
  "userType": enum (UserType)
}
Felder
userId

string

Ressourcenname eines Chat-Nutzers. Format: users/{user}.
displayName

string

Der Anzeigename eines Chat-Nutzers.
email

string

Die E-Mail-Adresse des Nutzers. Dieses Feld wird nur ausgefüllt, wenn der Nutzertyp HUMAN ist.
userType

enum (UserType)

Der Typ des Nutzers.

ChatAttachmentMetadata

JSON-Darstellung 
{
  "attachmentId": string,
  "filename": string,
  "mimeType": string,
  "source": enum (Source),
  "driveFileId": string
}
Felder
attachmentId

string

Ressourcenname des Anhangs. Format: spaces/{space}/messages/{message}/attachments/{attachment}.
filename

string

Name des Anhangs.
mimeType

string

Inhaltstyp (MIME-Typ).
source

enum (Source)

Die Quelle des Anhangs.
driveFileId

string

Nur Ausgabe. Die ID der Google Drive-Datei. Wird nur ausgefüllt, wenn die Quelle DRIVE_FILE ist. Verwendung mit dem Google Drive-MCP.

ReactionSummary

JSON-Darstellung 
{
  "emoji": string,
  "count": integer
}
Felder
emoji

string

Der Unicode-String des Emojis oder der Name des benutzerdefinierten Emojis.
count

integer

Die Gesamtzahl der Reaktionen mit dem zugehörigen Emoji.

QuotedMessageMetadata

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

string

Nur Ausgabe. Ressourcenname der ursprünglichen Nachricht, die zitiert oder weitergeleitet wird. Format: spaces/{space}/messages/{message}
lastUpdateTime

string

Nur Ausgabe. Zeitstempel, der angibt, wann die ursprüngliche Nachricht erstellt oder zuletzt aktualisiert wurde, bevor sie zitiert oder weitergeleitet wurde. Format: ISO 8601-Zeitstempel.
quoteType

enum (QuoteType)

Nur Ausgabe. Die Art des Angebots.
plaintextBody

string

Nur Ausgabe. Snapshot des Textkörpers der ursprünglichen Nachricht zum Zeitpunkt des Zitierens oder Weiterleitens. Formatiert mit Markdown für FORWARD und Nur-Text für REPLY.
sender

string

Nur Ausgabe. Der Anzeigename des Autors der ursprünglichen Nachricht.
attachments[]

object (ChatAttachmentMetadata)

Nur Ausgabe. Anhänge, die Teil der ursprünglichen Nachricht waren. Wird nur für den Angebotstyp FORWARD ausgefüllt.
forwardedMetadata

object (ForwardedMetadata)

Nur Ausgabe. Metadaten zur Quellunterhaltung der weitergeleiteten Nachricht. Wird nur für den Angebotstyp FORWARD ausgefüllt.

ForwardedMetadata

JSON-Darstellung 
{
  "conversationId": string,
  "conversationDisplayName": string
}
Felder
conversationId

string

Nur Ausgabe. Der Ressourcenname der Quellunterhaltung. Format: spaces/{space}
conversationDisplayName

string

Nur Ausgabe. Der Anzeigename der Quellunterhaltung zum Zeitpunkt der Weiterleitung der Nachricht. Bei benannten Gruppenbereichen ist dies der Name des Gruppenbereichs. Bei Direktnachrichten (1:1) ist dies der Name des anderen Teilnehmers. Bei unbenannten Gruppenchats ist dies ein generierter Name, der auf den Namen der Mitglieder basiert.

UserType

Der Typ eines Google Chat-Nutzers.

Enums
USER_TYPE_UNSPECIFIED Nicht angegeben
HUMAN Menschlicher Nutzer.
APP App-Nutzer

Quelle

Die Quelle des Anhangs.

Enums
SOURCE_UNSPECIFIED Reserviert.
DRIVE_FILE Die Datei ist eine Google Drive-Datei.
UPLOADED_CONTENT Die Datei wird in Google Chat hochgeladen.

QuoteType

Der Zitattyp, der angibt, ob die Nachricht eine Antwort mit Zitat oder eine weitergeleitete Nachricht ist.

Enums
QUOTE_TYPE_UNSPECIFIED Reserviert. Nicht definierter Angebotstyp.
REPLY Die Nachricht ist eine Antwort mit Zitat auf eine ursprüngliche Nachricht im selben Thread.
FORWARD Die Nachricht wird von einer ursprünglichen Nachricht in einer anderen Unterhaltung oder von einem anderen Thread in derselben Unterhaltung weitergeleitet.

Tool-Annotationen

Tool-Anmerkungen werden an MCP-Clients gesendet, um das grundlegende Risiko eines bestimmten Tools zu beschreiben. Die meisten Clients behandeln diese Hinweise als nicht vertrauenswürdig, sie können aber verwendet werden, um zu entscheiden, wann eine Bestätigungsaufforderung an einen Nutzer gesendet werden soll.

Zusätzlich zum Titelstring werden die folgenden booleschen Hinweise definiert:

  • readOnlyHint: Wenn „true“, ändert das Tool seine Umgebung nicht. Standardeinstellung: false.
  • destructiveHint: Wenn „true“, kann das Tool destruktive Aktionen ausführen. Wenn „false“, kann das Tool nur additive Aktionen ausführen. Standardeinstellung: true.
  • idempotentHint: Wenn „true“, hat das wiederholte Aufrufen des Tools mit denselben Argumenten keine zusätzlichen Auswirkungen auf die Umgebung. Standardeinstellung: false.
  • openWorldHint: Wenn „true“, kann das Tool mit einer „offenen Welt“ externer Entitäten interagieren. Wenn „false“, kann das Tool nur mit internen Entitäten interagieren. Ein Tool für die Websuche wäre beispielsweise ein Open-World-Tool, ein Tool für gemerkte Informationen dagegen nicht.

Destruktiver Hinweis: ❌ | Idempotenter Hinweis: ✅ | Lesezugriff-Hinweis: ✅ | Open-World-Hinweis: ❌

Autorisierungsbereiche

Erfordert einen der folgenden OAuth-Bereiche:

  • 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