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 Inhalts der Nachricht, den Betreff, den Absender und die Empfänger. Mit dem Parameter view wird gesteuert, welche Felder in den zugehörigen Nachrichten ausgefüllt werden. Standardmäßig (oder mit THREAD_VIEW_MINIMAL) sind Betreff und Snippet enthalten. Verwenden Sie THREAD_VIEW_METADATA_ONLY, um Betreff und Snippet auszuschließen. Beachten Sie, dass mit diesem Tool nicht die vollständigen Nachrichtentexte zurückgegeben werden. Verwenden Sie das Tool „get_thread“ mit einer Thread-ID, um den vollständigen Nachrichtentext abzurufen, falls erforderlich. 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 nicht markierte Nachricht enthält, auch wenn andere E‑Mails in derselben Konversation 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 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--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

  "view": enum (ThreadView)
}
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 hilfreich, 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:<email> – Von einer bestimmten Person gesendet.
  • to:<email>: An eine bestimmte Person gesendet.
  • cc:<email> – Bestimmte Personen in Cc.
  • bcc:<email> – Bestimmte Personen im Feld „Bcc“.
  • deliveredto:<email> – An eine bestimmte Adresse geliefert.
  • list:<email>: Aus einer bestimmten Mailingliste.

Uhrzeit und Datum:

  • after:YYYY/MM/DD / newer:YYYY/MM/DD – Erhalten nach einem Datum.
  • before:YYYY/MM/DD / older:YYYY/MM/DD – Vor einem bestimmten Datum eingegangen.
  • older_than:<duration>: Älter als ein bestimmter Zeitraum (z. B. 1y, 2d).
  • newer_than:<duration> – Jünger als ein Zeitraum.

Inhalt:

  • subject:<words> – Wörter in der Betreffzeile.
  • has:<type> – Hat bestimmte Inhaltstypen (Anhang, Drive, YouTube, Dokument).
  • filename:<name>: Anhang mit einem bestimmten Namen oder Typ.
  • "<word/phrase>": Suche nach einem exakt übereinstimmenden Wort oder einer Wortgruppe (z. B. "holiday", "holiday vacation")
  • +<word> – Exakte Übereinstimmung mit einem Wort. (z. B. +holiday, +unicorn)
  • rfc822msgid:<id>: Header für eine bestimmte Nachrichten-ID.
  • AROUND <distance>: Wörter finden, die nah beieinander stehen (z. B. holiday AROUND 10 vacation).

Labels und Kategorien:

  • label:<name> – Unter einem bestimmten Label. Das Tool akzeptiert Label-IDs, nicht Anzeigenamen. Verwenden Sie das Tool „list_labels“, um die ID abzurufen.
  • category:<name> – In einer Kategorie („Allgemein“, „Soziale Netzwerke“, „Werbung“, „Benachrichtigungen“, „Foren“, „Reservierungen“, „Käufe“).
  • in:<label>: Suche in bestimmten Labels (Archiv, Verschoben, Papierkorb, Gesendet, Posteingang). Beispiele: in:trash, in:inbox Archivierte und gesendete Nachrichten sind standardmäßig enthalten. Verwenden Sie -in:archive und -in:sent, um sie auszuschließen. Entwürfe werden vom Tool standardmäßig explizit ausgeschlossen. Verwenden Sie in:inbox, um die Suche auf den Posteingang zu beschränken.
  • has:userlabels: Enthält Nutzerlabels.
  • has:nouserlabels: Hat keine Nutzerlabels.
  • has:*-star: Bestimmte Sternfarben (falls aktiviert, z. B. has:yellow-star).
  • in:draft: In Entwürfen suchen. -in:draft bedeutet, dass Entwürfe aus den Suchergebnissen ausgeschlossen werden.
  • in:sent: In gesendeten Nachrichten suchen.
  • in:anywhere: Suche in allen Ordnern, einschließlich „Spam“ und „Papierkorb“.

Status:

  • is:<status> – Nach Status suchen (wichtig, markiert, ungelesen, gelesen, stummgeschaltet).

Größe:

  • size:<bytes>: Die genaue Größe in Byte.
  • larger:<size> / smaller:<size>: Größer oder kleiner als eine bestimmte Größe (z. B. 10M für 10 MB).

Logik und Gruppierung:

  • AND: Alle Kriterien müssen erfüllt sein (Standardverhalten).
  • OR oder { }: Entspricht einem oder mehreren Kriterien (z. B. from:amy OR from:david, {from:amy from:david}).
  • - (Minuszeichen): Schließt Kriterien aus, 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. Threads aus dem Papierkorb in die Ergebnisse einbeziehen Die Standardeinstellung ist "false".

Union-Feld _view.

Für _view ist nur einer der folgenden Werte zulässig:
view

enum (ThreadView)

Optional. Steuert die Felder, die für Threads in der Threadliste ausgefüllt werden. Die Standardeinstellung ist THREAD_VIEW_MINIMAL. THREAD_VIEW_MINIMAL gibt id, snippet, subject, from, to, cc, date, labelIds zurück. THREAD_VIEW_METADATA_ONLY gibt „id“, „from“, „to“, „cc“, „date“ und „labelIds“ zurück.

ThreadView

Enumeration zur Steuerung der Felder, die für Threads in der Antwort von „ListThreads“ und „SearchThreads“ ausgefüllt werden.

Enums
THREAD_VIEW_UNSPECIFIED Wird für die Abwärtskompatibilität auf THREAD_VIEW_MINIMAL abgebildet.
THREAD_VIEW_METADATA_ONLY Gibt „id“, „from“, „to“, „cc“, „date“ und „labelIds“ zurück.
THREAD_VIEW_MINIMAL Gibt „id“, „snippet“, „subject“, „from“, „to“, „cc“, „date“ und „labelIds“ zurück.

Ausgabeschema

Antwortnachricht für den RPC „SearchThreads“.

SearchThreadsResponse

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

object (Thread)

Liste der Zusammenfassungen von Threads.
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.
resultCountEstimate

string (int64 format)

Die geschätzte Anzahl der Ergebnisse für diese Abfrage. Sie sollte als Untergrenze betrachtet werden. Wenn sie beispielsweise 500 beträgt, kann die Anzahl dem Nutzer als „500+“ gemeldet werden.

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
  ],
  "htmlBody": string,
  "attachments": [
    {
      object (AttachmentMetadata)
    }
  ],
  "labelIds": [
    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 die E-Mail-Adressen der Empfänger.
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, wird 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.
htmlBody

string

Der HTML-Inhalt der E-Mail. Wird nur ausgefüllt, wenn MessageFormat FULL_CONTENT ist.
attachments[]

object (AttachmentMetadata)

Nur Ausgabe. Die Anhänge werden nur ausgefüllt, wenn MessageFormat FULL_CONTENT war.
labelIds[]

string

Die IDs der Labels, die an die Nachricht angehängt sind. Enthält IDs von Nutzerlabels und Standard-Systemlabels, die auf INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, SENT, DRAFT, CHAT beschränkt sind.

AttachmentMetadata

JSON-Darstellung 
{
  "id": string,
  "mimeType": string,
  "filename": string
}
Felder
id

string

Nur Ausgabe. Die ID des Anhangs.
mimeType

string

Der MIME-Typ des Anhangs.
filename

string

Der Dateiname des Anhangs.

Tool-Annotationen

Destruktiver Hinweis: ❌ | Idempotenter Hinweis: ✅ | Hinweis „Nur lesen“: ✅ | Hinweis „Offene Welt“: ❌

Autorisierungsbereiche

Erfordert einen der folgenden OAuth-Bereiche:

  • https://mail.google.com/
  • https://www.googleapis.com/auth/gmail.modify
  • https://www.googleapis.com/auth/gmail.readonly