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. Tieni presente che questo strumento non restituisce i corpi completi dei messaggi; utilizza lo strumento "get_thread" con un ID thread per recuperare il corpo completo del messaggio, se necessario. 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 intero thread 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.

Curl Request 
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
}'

Schema di input

Messaggio di richiesta per la RPC SearchThreads.

SearchThreadsRequest

Rappresentazione JSON 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean
}
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 chiamata SearchThreads precedente, soprattutto quando il numero di thread corrispondenti alla query supera il limite di 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 elencate tutte le conversazioni (esclusi spam e cestino per impostazione predefinita).

Operatori supportati per categoria:

Mittente e destinatario: from: - Inviato da una persona specifica. A: - Inviato a una persona specifica. cc: - Persone specifiche in Cc. bcc: - Persone specifiche in Ccn. deliveredto: - Consegna a un indirizzo specifico. list: - Da una mailing list specifica.

Ora e data: after:AAAA/MM/GG / newer:AAAA/MM/GG - Ricevuto dopo una data. before:AAAA/MM/GG / older:AAAA/MM/GG - Ricevuto prima di una data. older_than: - Più vecchio di una durata (ad es. 1 anno, 2 giorni). newer_than: - Più recente di una durata.

Contenuti: oggetto: - Parole nella riga dell'oggetto. has: - Contiene tipi di contenuti specifici (allegato, drive, YouTube, documento). filename: - Allegato con un nome o un tipo specifico. "<parola/frase>": cerca una parola o una frase esatta. ad esempio "vacanza", "vacanza". + - Trova una parola esatta. (ad es. +vacanze, +unicorno) rfc822msgid: - Intestazione ID messaggio specifico. AROUND : trova parole vicine tra di loro (ad es. vacanza AROUND 10 vacanza).

Etichette e categorie: label: - In un'etichetta specifica. Lo strumento accetta ID etichetta, non nomi visualizzati. Utilizza lo strumento list_labels per ottenere l'ID. category: - In una categoria (principale, social, promozioni, aggiornamenti, forum, prenotazioni, acquisti). in:

Stato: is: - Cerca per stato (importante, con stella, da leggere, letto, silenziato).

Dimensioni: size: - Dimensioni specifiche in byte. larger: / smaller: - Più grande o più piccolo di una dimensione (ad es. 10M per 10 MB).

Logica e raggruppamento: AND: corrispondenza di tutti i criteri (comportamento predefinito). OR o { } - Corrispondenza con uno o più criteri (ad es. from:amy OR from:david, {from:amy from:david}). - (meno) - Escludi criteri (ad es. -film). ( ) - Raggruppa più termini di ricerca (ad es. 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 bozze del CESTINO nei risultati. Il valore predefinito è false.

Schema di output

Messaggio di risposta per la RPC SearchThreads.

SearchThreadsResponse

Rappresentazione JSON 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": 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 dei 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 della successiva SearchThreadsRequest.

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
  ]
}
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.

Annotazioni dello strumento

Suggerimento distruttivo: ❌ | Suggerimento idempotente: ✅ | Suggerimento di sola lettura: ✅ | Suggerimento di mondo aperto: ❌