MCP Tools Reference: gmailmcp.googleapis.com

Strumento: search_threads

Elenca le conversazioni email dell'account Gmail dell'utente autenticato.

Questo strumento può filtrare i thread in base a una stringa di query e supporta la paginazione. Restituisce un elenco di thread, inclusi i relativi ID e messaggi correlati. Ogni messaggio correlato contiene dettagli come uno snippet del corpo del messaggio, l'oggetto, il mittente, i destinatari e così via. Il parametro view controlla quali campi vengono compilati nei messaggi correlati. Per impostazione predefinita (o con THREAD_VIEW_MINIMAL), include l'oggetto e lo snippet. Utilizza THREAD_VIEW_METADATA_ONLY per escludere l'oggetto e lo snippet. Tieni presente che questo strumento non restituisce i corpi completi dei messaggi. Se necessario, utilizza lo strumento "get_thread" con un ID thread per recuperare il corpo completo del messaggio. I thread con i criteri esclusi potrebbero comunque essere visualizzati nei risultati. Ciò accade perché Gmail identifica prima i messaggi corrispondenti. Ad esempio, se cerchi -is:starred, Gmail troverà un'intera conversazione se contiene almeno un messaggio rimosso da Speciali, anche se altre email della stessa conversazione sono aggiunte a Speciali.

Il seguente esempio mostra come utilizzare curl per richiamare lo strumento MCP search_threads.

Richiesta 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
}'

Schema di input

Messaggio di richiesta per la RPC SearchThreads.

SearchThreadsRequest

Rappresentazione JSON 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean

  "view": enum (ThreadView)
}
Campi

Campo unione _page_size.

_page_size può essere solo uno dei seguenti tipi:
pageSize

integer

Facoltativo. Il numero massimo di thread da restituire. Se non specificato, il valore predefinito è 20. Il valore massimo consentito è 50.

Campo unione _page_token.

_page_token può essere solo uno dei seguenti tipi:
pageToken

string

Facoltativo. Token di pagina per recuperare una pagina specifica di risultati nell'elenco. Lascia vuoto per recuperare la prima pagina. Viene utilizzato principalmente per la paginazione per continuare a recuperare i risultati dal punto in cui si è interrotta la precedente chiamata SearchThreads, soprattutto quando il numero di thread corrispondenti alla query supera il limite page_size.

Campo unione _query.

_query può essere solo uno dei seguenti tipi:
query

string

Facoltativo. Una stringa di query per filtrare i thread. Per utilizzare questo strumento, le query in linguaggio naturale devono essere pre-convertite in query con sintassi Gmail. Se omesso, vengono elencati tutti i thread (esclusi spam e cestino per impostazione predefinita).

Operatori supportati per categoria:

Mittente e destinatario:

  • from:<email>: inviati da una persona specifica.
  • to:<email>: inviato a una persona specifica.
  • cc:<email>: persone specifiche in Cc.
  • bcc:<email>: persone specifiche in Ccn.
  • deliveredto:<email>: consegnato a un indirizzo specifico.
  • list:<email>: da una mailing list specifica.

Ora e data:

  • after:YYYY/MM/DD / newer:YYYY/MM/DD: ricevuto dopo una data.
  • before:YYYY/MM/DD / older:YYYY/MM/DD: ricevuto prima di una data.
  • older_than:<duration>: più vecchio di una durata (ad esempio, 1y, 2d).
  • newer_than:<duration>: più recente di una durata.

Contenuti:

  • subject:<words>: parole nella riga dell'oggetto.
  • has:<type>: contiene tipi di contenuti specifici (allegato, drive, YouTube, documento).
  • filename:<name>: allegato con un nome o un tipo specifico.
  • "<word/phrase>": cerca una parola o una frase esatta. ad esempio, "holiday", "holiday vacation".
  • +<word>: trova corrispondenza esatta di una parola. (ad esempio, +holiday, +unicorn)
  • rfc822msgid:<id>: intestazione ID messaggio specifica.
  • AROUND <distance>: trova parole vicine tra di loro (ad esempio, holiday AROUND 10 vacation).

Etichette e categorie:

  • label:<name>: sotto un'etichetta specifica. Lo strumento accetta gli ID delle etichette, non i nomi visualizzati. Utilizza lo strumento list_labels per ottenere l'ID.
  • category:<name>: in una categoria (principale, social, promozioni, aggiornamenti, forum, prenotazioni, acquisti).
  • in:<label>: cerca in etichette specifiche (archivio, posticipate, cestino, inviate, posta in arrivo). Ad esempio, in:trash, in:inbox. I messaggi archiviati e inviati sono inclusi per impostazione predefinita; utilizza -in:archive e -in:sent per escluderli. Per impostazione predefinita, le bozze vengono escluse in modo esplicito dallo strumento. Utilizza in:inbox per limitare la ricerca alla sola posta in arrivo.
  • has:userlabels: contiene etichette utente.
  • has:nouserlabels: non ha etichette utente.
  • has:*-star: colori specifici delle stelle (se abilitati, ad esempio has:yellow-star).
  • in:draft: cerca nelle bozze. -in:draft significa escludere le bozze dai risultati di ricerca.
  • in:sent: cerca nei messaggi inviati.
  • in:anywhere: cerca in tutte le cartelle (incluse Spam e Cestino).

Stato:

  • is:<status>: cerca per stato (importante, speciale, da leggere, letto, silenziato).

Dimensioni:

  • size:<bytes>: dimensioni specifiche in byte.
  • larger:<size> / smaller:<size>: maggiore o minore di una dimensione (ad esempio, 10M per 10 MB).

Logica e raggruppamento:

  • AND: corrispondenza di tutti i criteri (comportamento predefinito).
  • OR o { }: corrisponde a uno o più criteri (ad esempio, from:amy OR from:david, {from:amy from:david}).
  • - (meno) - Escludi criteri (ad esempio, -movie).
  • ( ): raggruppa più termini di ricerca (ad esempio, subject:(dinner film)).

Esempi:

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

Campo unione _include_trash.

_include_trash può essere solo uno dei seguenti tipi:
includeTrash

boolean

Facoltativo. Includi le discussioni del CESTINO nei risultati. Il valore predefinito è false.

Campo unione _view.

_view può essere solo uno dei seguenti tipi:
view

enum (ThreadView)

Facoltativo. Controlla i campi compilati per i thread nell'elenco dei thread. Il valore predefinito è THREAD_VIEW_MINIMAL. THREAD_VIEW_MINIMAL restituisce id, snippet, oggetto, da, a, cc, data, labelIds. THREAD_VIEW_METADATA_ONLY restituisce id, da, a, cc, data, labelIds.

ThreadView

Enumerazione per controllare i campi compilati per i thread nelle risposte ListThreads e SearchThreads.

Enum
THREAD_VIEW_UNSPECIFIED Mappa a THREAD_VIEW_MINIMAL per la compatibilità con le versioni precedenti.
THREAD_VIEW_METADATA_ONLY Restituisce id, da, a, cc, data, labelIds.
THREAD_VIEW_MINIMAL Restituisce id, snippet, oggetto, da, a, cc, data, labelIds.

Schema di output

Messaggio di risposta per la RPC SearchThreads.

SearchThreadsResponse

Rappresentazione JSON 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": string,
  "resultCountEstimate": string
}
Campi
threads[]

object (Thread)

Elenco dei riepiloghi dei thread.
nextPageToken

string

Un token che può essere utilizzato in una chiamata successiva per recuperare la pagina successiva di thread. Presente solo se sono presenti altri risultati. Se il numero di thread corrispondenti alla query supera il limite page_size, la risposta conterrà un next_page_token. Per recuperare la pagina successiva dei risultati, passa questo token nel campo page_token del successivo SearchThreadsRequest.
resultCountEstimate

string (int64 format)

Il conteggio dei risultati stimato per questa query. Deve essere trattato come limite inferiore, quindi, ad esempio, se è 500, il conteggio può essere segnalato all'utente come "500+".

Thread

Rappresentazione JSON 
{
  "id": string,
  "messages": [
    {
      object (Message)
    }
  ]
}
Campi
id

string

L'identificatore univoco del thread.
messages[]

object (Message)

Un elenco di messaggi nel thread, ordinati cronologicamente.

Messaggio

Rappresentazione 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
  ]
}
Campi
id

string

L'identificatore univoco del messaggio.
snippet

string

Snippet del corpo del messaggio.
subject

string

L'oggetto del messaggio estratto dalle intestazioni:
sender

string

Indirizzo email del mittente.
toRecipients[]

string

Agli indirizzi email dei destinatari.
ccRecipients[]

string

Indirizzi email dei destinatari in Cc.
date

string

Data del messaggio nel formato ISO 8601 (AAAA-MM-GG).
plaintextBody

string

Contenuto completo del corpo, compilato solo se MessageFormat era FULL_CONTENT.
attachmentIds[]

string

Solo output. Gli ID allegato, compilati solo se MessageFormat era FULL_CONTENT.
htmlBody

string

Il contenuto HTML dell'email, compilato solo se MessageFormat era FULL_CONTENT.
attachments[]

object (AttachmentMetadata)

Solo output. Gli allegati, compilati solo se MessageFormat era FULL_CONTENT.
labelIds[]

string

Gli ID delle etichette allegate al messaggio. Include gli ID delle etichette utente e delle etichette di sistema standard limitate a INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, SENT, DRAFT, CHAT.

AttachmentMetadata

Rappresentazione JSON 
{
  "id": string,
  "mimeType": string,
  "filename": string
}
Campi
id

string

Solo output. L'ID dell'allegato.
mimeType

string

Il tipo MIME dell'allegato.
filename

string

Il nome del file dell'allegato.

Annotazioni dello strumento

Suggerimento distruttivo: ❌ | Suggerimento idempotente: ✅ | Suggerimento di sola lettura: ✅ | Suggerimento open world: ❌

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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