MCP Tools Reference: chatmcp.googleapis.com

Tool: search_conversations

Sucht nach Google Chat-Unterhaltungen, um Unterhaltungs-IDs zu finden. Benannte Gruppenbereiche werden anhand des Anzeigenamens (space_name_query) gefunden. Direktnachrichten (DMs) und Gruppenchats werden nur anhand der E‑Mail-Adressen der Teilnehmer (participants) gefunden.

Dieses Tool durchsucht Unterhaltungsmetadaten, NICHT Nachrichteninhalte. Wenn Sie im Nachrichtenverlauf suchen oder Nachrichten nach Keyword, Absender oder Zeitstempel finden möchten, verwenden Sie search_messages.

Wenn nur participants angegeben sind, sucht dieses Tool nach 1:1-Direktnachrichten (wenn ein Teilnehmer angegeben ist) oder Gruppenchats (wenn mehrere Teilnehmer angegeben sind), die die angegebenen Teilnehmer und den aufrufenden Nutzer enthalten. Benannte Gruppenbereiche werden nicht zurückgegeben.

Wenn nur ein space_name_query angegeben wird, sucht dieses Tool NUR in benannten Spaces, bei denen die Abfrage ein Teilstring des Anzeigenamens des Space ist, wobei die Groß-/Kleinschreibung nicht berücksichtigt wird. Direktnachrichten und Gruppenchats werden nie zurückgegeben. Übergeben Sie daher NICHT den Namen einer Person als space_name_query, um eine Direktnachricht mit ihr zu finden. Suchen Sie stattdessen nach ihrer E‑Mail-Adresse und übergeben Sie diese in participants.

Wenn sowohl participants als auch space_name_query angegeben sind, sucht dieses Tool nach Direktnachrichten oder Gruppenchats nach Teilnehmern und filtert sie dann nach Anzeigename.

Wenn weder participants noch space_name_query angegeben ist, werden mit diesem Tool benannte Gruppenbereiche aufgelistet, in denen der aufrufende Nutzer Mitglied ist (Direktnachrichten und Gruppenchats sind nicht enthalten).

Dieses Tool listet nur Unterhaltungen auf, an denen der aufrufende Nutzer beteiligt ist.

Gibt eine Liste von Konversationsobjekten mit Konversations-IDs (Format: spaces/{space}), Anzeigenamen und Konversationstypen zurück.

WICHTIG: Eine leere conversations-Liste bedeutet nicht, dass es insgesamt keine weiteren Ergebnisse gibt. Wenn next_page_token vorhanden ist, können weitere Seiten abgerufen werden. Wenn du eine leere Liste, aber einen next_page_token erhältst, frage den Nutzer, ob du die Suche fortsetzen sollst.

Das folgende Codebeispiel zeigt, wie Sie mit curl das MCP-Tool search_conversations 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_conversations",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Eingabeschema

SearchConversationsRequest

JSON-Darstellung 
{
  "spaceNameQuery": string,
  "pageSize": integer,
  "pageToken": string,
  "participants": [
    string
  ]
}
Felder
spaceNameQuery

string

Optional. Der Text, nach dem in den Anzeigenamen von Unterhaltungen gesucht werden soll (Teilstring-Übereinstimmung ohne Berücksichtigung der Groß-/Kleinschreibung).

Wenn participants leer ist, werden nur benannte Gruppenbereiche durchsucht. Direktnachrichten (DMs) und Gruppenchats werden nie zurückgegeben. Wenn Sie also nach dem Namen einer Person suchen, wird keine DM mit ihr gefunden. Wenn Sie eine Direktnachricht oder einen Gruppenchat suchen möchten, geben Sie stattdessen die E-Mail-Adressen der Mitglieder in participants an. Wenn participants festgelegt ist, werden die übereinstimmenden Direktnachrichten oder Gruppenchats mit dieser Abfrage weiter nach Anzeigename gefiltert.
pageSize

integer

Optional. Die maximale Anzahl der zurückzugebenden Spaces. Der Dienst gibt möglicherweise weniger als diesen Wert zurück. Wenn nicht angegeben, werden maximal 20 Spaces zurückgegeben. Der Höchstwert beträgt 1.000. Werte über 1.000 werden implizit auf 1.000 umgewandelt.
pageToken

string

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

string

Optional. Liste der E‑Mail-Adressen der Teilnehmer, um die Unterhaltungen zu filtern, mit Ausnahme des Anrufers. Damit können Sie Direktnachrichten (DMs) und Gruppenchats finden: Wenn Sie einen einzelnen Teilnehmer eingeben, wird die 1:1-DM mit dieser Person zurückgegeben. Wenn Sie mehrere Teilnehmer eingeben, werden Gruppenchats mit allen diesen Teilnehmern zurückgegeben. Benannte Gruppenbereiche werden nicht zurückgegeben, wenn dieses Feld festgelegt ist.

Ausgabeschema

Antwort mit der Liste der übereinstimmenden Unterhaltungen.

SearchConversationsResponse

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

object (Conversation)

Liste der Unterhaltungsobjekte, die den Suchkriterien entsprechen. Jede Unterhaltung enthält die conversation_id (Format: spaces/{space}), den display_name, den conversation_type und den last_active_timestamp.
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.

Wird nur ausgefüllt, wenn die Anfrage nach participants gefiltert wird.

Unterhaltung

JSON-Darstellung 
{
  "conversationId": string,
  "displayName": string,
  "conversationType": enum (ConversationType),
  "lastActiveTimestamp": string
}
Felder
conversationId

string

Die ID der Unterhaltung (z.B. „spaces/AAAAAAAAA“).
displayName

string

Der Anzeigename der Unterhaltung. 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.
conversationType

enum (ConversationType)

Die Art der Unterhaltung (DIRECT_MESSAGE, GROUP_CHAT oder NAMED_SPACE).
lastActiveTimestamp

string (Timestamp format)

Der Zeitpunkt der letzten Aktivität in der Unterhaltung im ISO 8601-Format.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30".

Zeitstempel

JSON-Darstellung 
{
  "seconds": string,
  "nanos": integer
}
Felder
seconds

string (int64 format)

Stellt Sekunden der UTC-Zeit seit Unix-Epoche 1970-01-01T00:00:00Z dar. Muss zwischen -62135596800 und 253402300799 (einschließlich) liegen, was 0001-01-01T00:00:00Z bis 9999-12-31T23:59:59Z entspricht.
nanos

integer

Nicht negative Sekundenbruchteile Nanosekunden-Auflösung. Dieses Feld ist der Nanosekundenanteil der Dauer, keine Alternative zu Sekunden. Negative Sekundenwerte mit Bruchteilen müssen weiterhin nicht negative Nano-Werte haben, die zeitlich vorwärts gezählt werden. Muss zwischen 0 und 999.999.999 (einschließlich) liegen.

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.

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 jedoch 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 frei verfügbar, ein Tool für gemerkte Informationen jedoch nicht.

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

Autorisierungsbereiche

Erfordert einen der folgenden OAuth-Bereiche:

  • https://www.googleapis.com/auth/chat.memberships.readonly
  • https://www.googleapis.com/auth/chat.spaces
  • https://www.googleapis.com/auth/chat.spaces.readonly