MCP Tools Reference: gmailmcp.googleapis.com

Tool: search_threads

Listet E‑Mail-Konversationen aus dem Gmail-Konto des authentifizierten Nutzers auf.

Mit diesem Tool können Threads anhand eines Abfragestrings gefiltert werden. Außerdem wird die Paginierung unterstützt. Es wird eine Liste von Threads zurückgegeben, einschließlich ihrer IDs und zugehörigen Nachrichten. Jede zugehörige Nachricht enthält Details wie einen Ausschnitt des Nachrichtentexts, den Betreff, den Absender und die Empfänger. Beachten Sie, dass mit diesem Tool nicht der vollständige Nachrichtentext zurückgegeben wird. Verwenden Sie das Tool „get_thread“ mit einer Thread-ID, um den vollständigen Nachrichtentext abzurufen. Threads mit ausgeschlossenen Kriterien können weiterhin in den Ergebnissen angezeigt werden. Das liegt daran, dass Gmail zuerst übereinstimmende Nachrichten identifiziert. Wenn Sie beispielsweise nach -is:starred suchen, findet Gmail einen ganzen Thread, wenn er mindestens eine Nachricht ohne Stern enthält, auch wenn andere E‑Mails in derselben Konversation mit einem Stern markiert sind.

Im folgenden Beispiel wird gezeigt, wie Sie mit curl das MCP-Tool search_threads aufrufen.

Curl-Anfrage 
curl --location 'https://gmailmcp.googleapis.com/mcp/v1' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "search_threads",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Eingabeschema

Anfragenachricht für den RPC „SearchThreads“.

SearchThreadsRequest

JSON-Darstellung 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean
}
Felder

Union-Feld _page_size.

Für _page_size ist nur einer der folgenden Werte zulässig:
pageSize

integer

Optional. Die maximale Anzahl der zurückzugebenden Threads. Wenn nichts anderes angegeben wird, wird der Wert standardmäßig auf 20 gesetzt. Der maximal zulässige Wert beträgt 50.

Union-Feld _page_token.

Für _page_token ist nur einer der folgenden Werte zulässig:
pageToken

string

Optional. Seitentoken zum Abrufen einer bestimmten Ergebnisseite in der Liste. Lassen Sie das Feld leer, um die erste Seite abzurufen. Dieser Parameter wird hauptsächlich für die Paginierung verwendet, um Ergebnisse abzurufen, die beim vorherigen SearchThreads-Aufruf nicht berücksichtigt wurden. Das ist besonders dann nützlich, wenn die Anzahl der Threads, die der Abfrage entsprechen, das Limit für „page_size“ überschreitet.

Union-Feld _query.

Für _query ist nur einer der folgenden Werte zulässig:
query

string

Optional. Ein Abfragestring zum Filtern der Threads. Anfragen in natürlicher Sprache müssen vor der Verwendung dieses Tools in Gmail-Syntaxanfragen umgewandelt werden. Wenn das Flag nicht angegeben ist, werden alle Threads (mit Ausnahme von Spam und Papierkorb) aufgelistet.

Unterstützte Operatoren nach Kategorie:

Absender und Empfänger: from: – Von einer bestimmten Person gesendet. An :An eine bestimmte Person gesendet. cc: – Bestimmte Personen in Cc. bcc: – Bestimmte Personen in Bcc. deliveredto: – An eine bestimmte Adresse geliefert. list: - Aus einer bestimmten Mailingliste.

Zeit und Datum: after:JJJJ/MM/TT / newer:JJJJ/MM/TT – nach einem bestimmten Datum empfangen. before:JJJJ/MM/TT / older:JJJJ/MM/TT – Vor einem bestimmten Datum empfangen. older_than: – Älter als ein Zeitraum (z.B. 1 Jahr, 2 Tage). newer_than: – Jünger als ein Zeitraum.

Inhalt: Betreff: – Wörter in der Betreffzeile. has: – Enthält bestimmte Inhaltstypen (Anhang, Drive, YouTube, Dokument). filename: – Anhang mit einem bestimmten Namen oder Typ. „<Wort/Wortgruppe>“: Suche nach einem exakt übereinstimmenden Wort oder einer Wortgruppe. z. B. „Urlaub“, „Ferien“ + : Ein Wort muss genau übereinstimmen. z.B. +Urlaub, +Einhorn) rfc822msgid: – Header für eine bestimmte Nachrichten-ID. AROUND : Damit suchen Sie nach Wörtern, die in einem bestimmten Abstand zueinander stehen (z.B. „Feiertag AROUND 10 Urlaub“).

Labels und Kategorien: label: – Unter einem bestimmten Label. Das Tool akzeptiert Label-IDs, nicht Anzeigenamen. Verwenden Sie das Tool „list_labels“, um die ID abzurufen. category: – In einer Kategorie („primary“, „social“, „promotions“, „updates“, „forums“, „reservations“, „purchases“). in:

Status: is: – nach Status suchen (wichtig, markiert, ungelesen, gelesen, stummgeschaltet).

Größe: size: – Bestimmte Größe in Byte. larger: / smaller: – Größer oder kleiner als eine bestimmte Größe (z.B. 10M für 10 MB).

Logik und Gruppierung: UND – Alle Kriterien müssen erfüllt sein (Standardverhalten). ODER oder { } – Entspricht einem oder mehreren Kriterien (z.B. from:amy OR from:david, {from:amy from:david}). – (Minuszeichen): Kriterien ausschließen (z.B. -movie). ( ) – Mehrere Suchbegriffe gruppieren (z.B. subject:(dinner film)).

Beispiele: „subject:OneMCP Update“ „from:user@example.com“ „to:user2@example.com AND newer_than:7d“ „project proposal has:attachment“ „is:unread -in:draft“

Union-Feld _include_trash.

Für _include_trash ist nur einer der folgenden Werte zulässig:
includeTrash

boolean

Optional. Entwürfe aus dem Papierkorb in die Ergebnisse einbeziehen Die Standardeinstellung ist "false".

Ausgabeschema

Antwortnachricht für den RPC „SearchThreads“.

SearchThreadsResponse

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

object (Thread)

Liste der Zusammenfassungen von Unterhaltungen.
nextPageToken

string

Ein Token, das in einem nachfolgenden Aufruf verwendet werden kann, um die nächste Seite mit Threads abzurufen. Wird nur angezeigt, wenn es weitere Ergebnisse gibt. Wenn die Anzahl der Threads, die der Anfrage entsprechen, das Limit für „page_size“ überschreitet, enthält die Antwort ein next_page_token. Wenn Sie die nächste Ergebnisseite abrufen möchten, übergeben Sie dieses Token im Feld page_token des nächsten SearchThreadsRequest.

Thread

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

string

Die eindeutige ID des Threads.
messages[]

object (Message)

Eine Liste der Nachrichten im Thread, chronologisch sortiert.

Nachricht

JSON-Darstellung 
{
  "id": string,
  "snippet": string,
  "subject": string,
  "sender": string,
  "toRecipients": [
    string
  ],
  "ccRecipients": [
    string
  ],
  "date": string,
  "plaintextBody": string,
  "attachmentIds": [
    string
  ]
}
Felder
id

string

Die eindeutige ID der Nachricht.
snippet

string

Snippet des Nachrichtentexts.
subject

string

Der aus Headern extrahierte Betreff der Nachricht:
sender

string

E‑Mail-Adresse des Absenders.
toRecipients[]

string

An E-Mail-Adressen von Empfängern.
ccRecipients[]

string

E-Mail-Adressen der Cc-Empfänger.
date

string

Das Datum der Nachricht im ISO 8601-Format (JJJJ-MM-TT).
plaintextBody

string

Vollständiger Textinhalt, nur ausgefüllt, wenn MessageFormat FULL_CONTENT war.
attachmentIds[]

string

Nur Ausgabe. Die Anhänge-IDs werden nur ausgefüllt, wenn MessageFormat FULL_CONTENT war.

Tool-Annotationen

Destruktiver Hinweis: ❌ | Idempotenter Hinweis: ✅ | Nur-Lese-Hinweis: ✅ | Open-World-Hinweis: ❌