MCP Tools Reference: gmailmcp.googleapis.com

Ferramenta: search_threads

Lista as conversas por e-mail da conta do Gmail do usuário autenticado.

Ela pode filtrar conversas com base em uma string de consulta e é compatível com paginação. Ele retorna uma lista de conversas, incluindo os IDs e as mensagens relacionadas. Cada mensagem relacionada contém detalhes como um snippet do corpo da mensagem, o assunto, o remetente, os destinatários etc. O parâmetro view controla quais campos são preenchidos nas mensagens relacionadas. Por padrão (ou com THREAD_VIEW_MINIMAL), ele inclui assunto e snippet. Use THREAD_VIEW_METADATA_ONLY para excluir assunto e snippet. Os corpos das mensagens completas não são retornados por essa ferramenta. Use a ferramenta "get_thread" com um ID de conversa para buscar o corpo da mensagem completo, se necessário. As conversas com critérios excluídos ainda podem aparecer nos resultados. Isso acontece porque o Gmail identifica primeiro as mensagens correspondentes. Por exemplo, se você pesquisar -is:starred, o Gmail vai encontrar uma conversa inteira se ela tiver pelo menos uma mensagem sem estrela, mesmo que outros e-mails na mesma conversa tenham estrela.

O exemplo a seguir demonstra como usar curl para invocar a ferramenta search_threads MCP.

Solicitação 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
}'

Esquema de entrada

Mensagem de solicitação para a RPC SearchThreads.

SearchThreadsRequest

Representação JSON 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean

  "view": enum (ThreadView)
}
Campos

Campo de união _page_size.

_page_size pode ser apenas de um dos tipos a seguir:
pageSize

integer

Opcional. O número máximo de encadeamentos a serem retornados. Se não for especificado, o padrão será 20. O valor máximo permitido é 50.

Campo de união _page_token.

_page_token pode ser apenas de um dos tipos a seguir:
pageToken

string

Opcional. Token de página para recuperar uma página específica de resultados na lista. Deixe em branco para buscar a primeira página. Usado principalmente para paginação, para continuar buscando resultados de onde a chamada SearchThreads anterior parou, especialmente quando o número de linhas de execução que correspondem à consulta excede o limite de "page_size".

Campo de união _query.

_query pode ser apenas de um dos tipos a seguir:
query

string

Opcional. Uma string de consulta para filtrar as linhas de execução. As consultas em linguagem natural precisam ser convertidas previamente em consultas de sintaxe do Gmail para usar essa ferramenta. Se omitido, todas as conversas (exceto spam e lixeira por padrão) serão listadas.

Operadores compatíveis por categoria:

Remetente e destinatário:

  • from:<email> — Enviada por uma pessoa específica.
  • to:<email>: enviado para uma pessoa específica.
  • cc:<email> — Pessoas específicas em Cc.
  • bcc:<email>: pessoas específicas em Cco.
  • deliveredto:<email>: entregue em um endereço específico.
  • list:<email>: de uma lista de e-mails específica.

Data e hora:

  • after:YYYY/MM/DD / newer:YYYY/MM/DD: recebido após uma data.
  • before:YYYY/MM/DD / older:YYYY/MM/DD: recebido antes de uma data.
  • older_than:<duration>: mais antigo que uma duração (por exemplo, 1y, 2d).
  • newer_than:<duration>: mais recente que uma duração.

Conteúdo:

  • subject:<words>: palavras na linha de assunto.
  • has:<type>: tem tipos de conteúdo específicos (anexo, Drive, YouTube, documento).
  • filename:<name>: anexo com um nome ou tipo específico.
  • "<word/phrase>": pesquise uma palavra ou frase exata. (por exemplo, "holiday", "holiday vacation").
  • +<word>: corresponde exatamente a uma palavra. (por exemplo, +holiday, +unicorn)
  • rfc822msgid:<id>: cabeçalho de ID de mensagem específico.
  • AROUND <distance>: encontre palavras próximas umas das outras (por exemplo, holiday AROUND 10 vacation).

Rótulos e categorias:

  • label:<name> — Em um marcador específico. A ferramenta aceita IDs de rótulo, não nomes de exibição. Use a ferramenta list_labels para receber o ID.
  • category:<name>: em uma categoria (principal, social, promoções, atualizações, fóruns, reservas, compras).
  • in:<label>: pesquise em marcadores específicos (arquivo, adiados, lixeira, enviados, caixa de entrada). Por exemplo: in:trash e in:inbox. As mensagens arquivadas e enviadas são incluídas por padrão. Use -in:archive e -in:sent para excluí-las. Os rascunhos são excluídos explicitamente por padrão pela ferramenta. Use in:inbox para restringir a pesquisa apenas à caixa de entrada.
  • has:userlabels: tem rótulos de usuário.
  • has:nouserlabels: não tem rótulos de usuário.
  • has:*-star: cores específicas das estrelas (se ativadas, por exemplo, has:yellow-star).
  • in:draft: pesquise nos rascunhos. -in:draft significa excluir rascunhos dos resultados da pesquisa.
  • in:sent: pesquise nas mensagens enviadas.
  • in:anywhere: pesquise em todas as pastas, incluindo "Spam" e "Lixeira".

Status:

  • is:<status>: pesquise por status (importante, com estrela, não lida, lida, silenciada).

Tamanho:

  • size:<bytes>: tamanho específico em bytes.
  • larger:<size> / smaller:<size>: maior ou menor que um tamanho (por exemplo, 10M para 10 MB).

Lógica e agrupamento:

  • AND: corresponde a todos os critérios (comportamento padrão).
  • OR ou { }: corresponda a um ou mais critérios (por exemplo, from:amy OR from:david, {from:amy from:david}).
  • - (sinal de menos): exclui critérios (por exemplo, -movie).
  • ( ): agrupe vários termos de pesquisa (por exemplo, subject:(dinner film)).

Exemplos:

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

Campo de união _include_trash.

_include_trash pode ser apenas de um dos tipos a seguir:
includeTrash

boolean

Opcional. Inclua conversas da LIXEIRA nos resultados. O padrão é "falso".

Campo de união _view.

_view pode ser apenas de um dos tipos a seguir:
view

enum (ThreadView)

Opcional. Controla os campos preenchidos para conversas na lista de conversas. O padrão é THREAD_VIEW_MINIMAL. THREAD_VIEW_MINIMAL retorna id, snippet, subject, from, to, cc, date, labelIds. THREAD_VIEW_METADATA_ONLY retorna id, from, to, cc, date, labelIds.

ThreadView

Enumeração para controlar os campos preenchidos para conversas na resposta "ListThreads" e "SearchThreads".

Tipos enumerados
THREAD_VIEW_UNSPECIFIED Corresponde a THREAD_VIEW_MINIMAL para compatibilidade com versões anteriores.
THREAD_VIEW_METADATA_ONLY Retorna id, from, to, cc, date, labelIds.
THREAD_VIEW_MINIMAL Retorna id, snippet, subject, from, to, cc, date, labelIds.

Esquema de saída

Mensagem de resposta para a RPC SearchThreads.

SearchThreadsResponse

Representação JSON 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": string,
  "resultCountEstimate": string
}
Campos
threads[]

object (Thread)

Lista de resumos de conversas.
nextPageToken

string

Um token que pode ser usado em uma chamada subsequente para recuperar a próxima página de conversas. Presente apenas se houver mais resultados. Se o número de linhas de execução que correspondem à consulta exceder o limite de page_size, a resposta vai conter um next_page_token. Para recuperar a próxima página de resultados, transmita esse token no campo page_token do próximo SearchThreadsRequest.
resultCountEstimate

string (int64 format)

A contagem de resultados estimada para esta consulta. Ele deve ser tratado como um limite inferior. Por exemplo, se for 500, a contagem poderá ser informada ao usuário como "500 ou mais".

Conversa

Representação JSON 
{
  "id": string,
  "messages": [
    {
      object (Message)
    }
  ]
}
Campos
id

string

O identificador exclusivo da conversa.
messages[]

object (Message)

Uma lista de mensagens na conversa, ordenadas cronologicamente.

Mensagem

Representação 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
  ]
}
Campos
id

string

O identificador exclusivo da mensagem.
snippet

string

Snippet do corpo da mensagem.
subject

string

O assunto da mensagem extraído dos cabeçalhos:
sender

string

Endereço de e-mail do remetente.
toRecipients[]

string

Para endereços de e-mail de destinatários.
ccRecipients[]

string

Endereços de e-mail dos destinatários em cópia.
date

string

Data da mensagem no formato ISO 8601 (AAAA-MM-DD).
plaintextBody

string

Conteúdo completo do corpo, preenchido apenas se MessageFormat for FULL_CONTENT.
attachmentIds[]

string

Apenas saída. Os IDs dos anexos, preenchidos apenas se MessageFormat for FULL_CONTENT.
htmlBody

string

O conteúdo HTML do e-mail, preenchido apenas se MessageFormat for FULL_CONTENT.
attachments[]

object (AttachmentMetadata)

Apenas saída. Os anexos, preenchidos apenas se MessageFormat for FULL_CONTENT.
labelIds[]

string

Os IDs dos rótulos anexados à mensagem. Inclui IDs de rótulos do usuário e rótulos padrão do sistema limitados a INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, SENT, DRAFT, CHAT.

AttachmentMetadata

Representação JSON 
{
  "id": string,
  "mimeType": string,
  "filename": string
}
Campos
id

string

Apenas saída. O ID do anexo.
mimeType

string

O tipo MIME do anexo.
filename

string

O nome do arquivo do anexo.

Anotações de ferramentas

Dica destrutiva: ❌ | Dica idempotente: ✅ | Dica somente leitura: ✅ | Dica de mundo aberto: ❌

Escopos de autorização

Requer um dos seguintes escopos do OAuth:

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