MCP Tools Reference: gmailmcp.googleapis.com

Outil : search_threads

Liste les fils de discussion de l'adresse e-mail du compte Gmail de l'utilisateur authentifié.

Cet outil peut filtrer les fils de discussion en fonction d'une chaîne de requête et est compatible avec la pagination. Elle renvoie une liste de fils de discussion, y compris leurs ID et les messages associés. Chaque message associé contient des informations telles qu'un extrait du corps du message, l'objet, l'expéditeur, les destinataires, etc. Le paramètre view contrôle les champs renseignés dans les messages associés. Par défaut (ou avec THREAD_VIEW_MINIMAL), il inclut l'objet et l'extrait. Utilisez THREAD_VIEW_METADATA_ONLY pour exclure l'objet et l'extrait. Notez que le corps complet des messages n'est pas renvoyé par cet outil. Utilisez l'outil "get_thread" avec un ID de fil de discussion pour récupérer le corps complet du message si nécessaire. Les fils de discussion contenant des critères exclus peuvent toujours apparaître dans les résultats. En effet, Gmail identifie d'abord les messages correspondants. Par exemple, si vous recherchez -is:starred, Gmail trouvera un fil de discussion entier s'il contient au moins un message non suivi, même si d'autres e-mails de la même conversation sont suivis.

L'exemple suivant montre comment utiliser curl pour appeler l'outil MCP search_threads.

Requête curl 
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
}'

Schéma d'entrée

Message de requête pour le RPC SearchThreads.

SearchThreadsRequest

Représentation JSON 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean

  "view": enum (ThreadView)
}
Champs

Champ d'union _page_size.

_page_size ne peut être qu'un des éléments suivants :
pageSize

integer

Facultatif. Nombre maximal de threads à renvoyer. Si aucune valeur n'est spécifiée, la valeur par défaut est 20. La valeur maximale autorisée est de 50.

Champ d'union _page_token.

_page_token ne peut être qu'un des éléments suivants :
pageToken

string

Facultatif. Jeton de page permettant de récupérer une page spécifique de résultats dans la liste. Laissez ce champ vide pour récupérer la première page. Il est principalement utilisé pour la pagination afin de continuer à récupérer les résultats là où l'appel SearchThreads précédent s'est arrêté, en particulier lorsque le nombre de threads correspondant à la requête dépasse la limite page_size.

Champ d'union _query.

_query ne peut être qu'un des éléments suivants :
query

string

Facultatif. Chaîne de requête permettant de filtrer les threads. Pour utiliser cet outil, les requêtes en langage naturel doivent être converties au préalable en requêtes de syntaxe Gmail. Si ce paramètre est omis, tous les fils de discussion (à l'exception du spam et de la corbeille par défaut) sont listés.

Opérateurs compatibles par catégorie :

Expéditeur et destinataire :

  • from:<email> : message envoyé par une personne spécifique.
  • to:<email> : envoyé à une personne spécifique.
  • cc:<email> : personnes spécifiques en copie Cc.
  • bcc:<email> : des personnes spécifiques en Cci.
  • deliveredto:<email> : livré à une adresse spécifique.
  • list:<email> : d'une liste de diffusion spécifique.

Date et heure :

  • after:YYYY/MM/DD / newer:YYYY/MM/DD : reçu après une date.
  • before:YYYY/MM/DD / older:YYYY/MM/DD : reçu avant une date donnée.
  • older_than:<duration> : plus ancien qu'une durée (par exemple, 1y, 2d).
  • newer_than:<duration> : plus récent qu'une durée.

Contenu :

  • subject:<words> : mots figurant dans la ligne d'objet.
  • has:<type> : contient des types de contenu spécifiques (pièce jointe, Drive, YouTube, document).
  • filename:<name> : pièce jointe portant un nom ou un type spécifique.
  • "<word/phrase>" : recherchez un mot ou une expression exacts. (par exemple, "holiday", "holiday vacation").
  • +<word> : correspond exactement à un mot. (par exemple, +holiday, +unicorn)
  • rfc822msgid:<id> : en-tête d'ID de message spécifique.
  • AROUND <distance> : trouvez les mots proches les uns des autres (par exemple, holiday AROUND 10 vacation).

Libellés et catégories :

  • label:<name> : sous un libellé spécifique. L'outil accepte les ID de libellé, et non les noms à afficher. Utilisez l'outil list_labels pour obtenir l'ID.
  • category:<name> : dans une catégorie (principale, réseaux sociaux, promotions, notifications, forums, réservations, achats).
  • in:<label> : recherchez des messages dans des libellés spécifiques (archive, mis en attente, corbeille, envoyés, boîte de réception). Par exemple, in:trash et in:inbox. Les messages archivés et envoyés sont inclus par défaut. Utilisez -in:archive et -in:sent pour les exclure. Par défaut, l'outil exclut explicitement les brouillons. Utilisez in:inbox pour limiter la recherche à la boîte de réception uniquement.
  • has:userlabels : comporte des libellés utilisateur.
  • has:nouserlabels : ne comporte aucun libellé utilisateur.
  • has:*-star : couleurs spécifiques des étoiles (si activées, par exemple, has:yellow-star).
  • in:draft : rechercher dans les brouillons. -in:draft signifie exclure les brouillons des résultats de recherche.
  • in:sent : recherchez dans les messages envoyés.
  • in:anywhere : effectuez une recherche dans tous les dossiers (y compris le spam et la corbeille).

État :

  • is:<status> : recherchez par état (important, suivi, non lu, lu, mis en sourdine).

Taille :

  • size:<bytes> : taille spécifique en octets.
  • larger:<size> / smaller:<size> : plus grand ou plus petit qu'une taille (par exemple, 10M pour 10 Mo).

Logique et regroupement :

  • AND : tous les critères doivent correspondre (comportement par défaut).
  • OR ou { } : correspond à un ou plusieurs critères (par exemple, from:amy OR from:david, {from:amy from:david}).
  • - (moins) : exclut des critères (par exemple, -movie).
  • ( ) : regroupez plusieurs termes de recherche (par exemple, subject:(dinner film)).

Exemples :

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

Champ d'union _include_trash.

_include_trash ne peut être qu'un des éléments suivants :
includeTrash

boolean

Facultatif. Incluez les fils de discussion de la CORBEILLE dans les résultats. Valeur par défaut : "false".

Champ d'union _view.

_view ne peut être qu'un des éléments suivants :
view

enum (ThreadView)

Facultatif. Contrôle les champs renseignés pour les fils de discussion dans la liste des fils de discussion. La valeur par défaut est THREAD_VIEW_MINIMAL. THREAD_VIEW_MINIMAL renvoie id, snippet, subject, from, to, cc, date, labelIds. THREAD_VIEW_METADATA_ONLY renvoie id, from, to, cc, date, labelIds.

ThreadView

Énumération permettant de contrôler les champs renseignés pour les fils de discussion dans les réponses ListThreads et SearchThreads.

Enums
THREAD_VIEW_UNSPECIFIED Mappe à THREAD_VIEW_MINIMAL pour la rétrocompatibilité.
THREAD_VIEW_METADATA_ONLY Renvoie les valeurs id, from, to, cc, date et labelIds.
THREAD_VIEW_MINIMAL Renvoie l'ID, l'extrait, l'objet, l'expéditeur, le destinataire, le destinataire en copie, la date et les ID de libellé.

Schéma de sortie

Message de réponse pour le RPC SearchThreads.

SearchThreadsResponse

Représentation JSON 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": string,
  "resultCountEstimate": string
}
Champs
threads[]

object (Thread)

Liste des résumés de fils de discussion.
nextPageToken

string

Jeton pouvant être utilisé dans un appel ultérieur pour récupérer la page suivante de fils de discussion. Présent uniquement si d'autres résultats sont disponibles. Si le nombre de fils de discussion correspondant à la requête dépasse la limite de page_size, la réponse contiendra un next_page_token. Pour récupérer la page de résultats suivante, transmettez ce jeton dans le champ page_token du prochain SearchThreadsRequest.
resultCountEstimate

string (int64 format)

Nombre de résultats estimé pour cette requête. Il doit être considéré comme une limite inférieure. Par exemple, s'il est de 500, le nombre peut être indiqué à l'utilisateur comme "500+".

Thread

Représentation JSON 
{
  "id": string,
  "messages": [
    {
      object (Message)
    }
  ]
}
Champs
id

string

Identifiant unique du fil de discussion.
messages[]

object (Message)

Liste des messages du fil de discussion, classés par ordre chronologique.

Message

Représentation JSON 
{
  "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
  ]
}
Champs
id

string

Identifiant unique du message.
snippet

string

Extrait du corps du message.
subject

string

Objet du message extrait des en-têtes :
sender

string

Adresse e-mail de l'expéditeur.
toRecipients[]

string

Adresses e-mail des destinataires.
ccRecipients[]

string

Adresses e-mail des destinataires en copie.
date

string

Date du message au format ISO 8601 (AAAA-MM-JJ).
plaintextBody

string

Contenu complet du corps, renseigné uniquement si MessageFormat est défini sur FULL_CONTENT.
attachmentIds[]

string

Uniquement en sortie. ID des pièces jointes, renseigné uniquement si MessageFormat est défini sur FULL_CONTENT.
htmlBody

string

Contenu HTML de l'e-mail, renseigné uniquement si MessageFormat est défini sur FULL_CONTENT.
attachments[]

object (AttachmentMetadata)

Uniquement en sortie. Pièces jointes, renseignées uniquement si MessageFormat est défini sur FULL_CONTENT.
labelIds[]

string

ID des libellés associés au message. Inclut les ID des libellés utilisateur et des libellés système standards limités à INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, SENT, DRAFT, CHAT.

AttachmentMetadata

Représentation JSON 
{
  "id": string,
  "mimeType": string,
  "filename": string
}
Champs
id

string

Uniquement en sortie. ID de la pièce jointe.
mimeType

string

Type MIME de la pièce jointe.
filename

string

Nom du fichier de la pièce jointe.

Annotations d'outils

Indication destructive : ❌ | Indication idempotente : ✅ | Indication en lecture seule : ✅ | Indication Open World : ❌

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

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