MCP Tools Reference: gmailmcp.googleapis.com

Ferramenta: search_threads

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

Essa ferramenta pode filtrar conversas com base em uma string de consulta e oferece suporte à paginação. Ela retorna uma lista de conversas, incluindo os IDs e as mensagens relacionadas. Cada mensagem relacionada contém detalhes como um trecho do corpo da mensagem, o assunto, o remetente, os destinatários etc. Os corpos completos das mensagens não são retornados por essa ferramenta. Use a ferramenta "get_thread" com um ID de conversa para buscar o corpo completo da mensagem, 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 MCP search_threads.

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

Esquema de entrada

Mensagem de solicitação para a RPC SearchThreads.

SearchThreadsRequest

Representação JSON 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean
}
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 conversas a serem retornadas. 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. Isso é usado principalmente para paginação, para continuar buscando resultados de onde a chamada SearchThreads anterior parou, especialmente quando o número de conversas 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 conversas. 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: - Enviado por uma pessoa específica. to: - Enviado para uma pessoa específica. cc: - Pessoas específicas em Cc. bcc: - Pessoas específicas em Cco. deliveredto: - Entregue a um endereço específico. list: - De uma lista de e-mails específica.

Hora e data: after:AAAA/MM/DD / newer:AAAA/MM/DD - Recebido após uma data. before:AAAA/MM/DD / older:AAAA/MM/DD - Recebido antes de uma data. older_than: - Mais antigo que uma duração (por exemplo, 1y, 2d). newer_than: - Mais recente que uma duração.

Conteúdo: subject: - Palavras na linha de assunto. has: - Tem tipos de conteúdo específicos (anexo, Drive, YouTube, documento). filename: - Anexo com um nome ou tipo específico. "<word/phrase>" - Uma palavra ou frase exata. Por exemplo: "feriado", "férias de feriado". + - Corresponde a uma palavra exatamente. Por exemplo, +feriado, +unicórnio rfc822msgid: - Cabeçalho de ID de mensagem específico. AROUND - Encontra palavras próximas umas das outras (por exemplo, feriado AROUND 10 férias).

Marcadores e categorias: label: - Em um marcador específico. A ferramenta aceita IDs de marcadores, não nomes de exibição. Use a ferramenta list_labels para receber o ID. category: - Em uma categoria (principal, social, promoções, atualizações, fóruns, reservas, compras). in:

Status: is: - Pesquisar por status (importante, com estrela, não lido, lido, silenciado).

Tamanho: size: - Tamanho específico em bytes. larger: / smaller: - 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 { } - Corresponde a um ou mais critérios (por exemplo, from:amy OR from:david, {from:amy from:david}). - (menos) - Exclui critérios (por exemplo, -filme). ( ) - Agrupa 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. Inclui rascunhos da LIXEIRA nos resultados. O padrão é "falso".

Esquema de saída

Mensagem de resposta para a RPC SearchThreads.

SearchThreadsResponse

Representação JSON 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": 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 conversas 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 da próxima SearchThreadsRequest.

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

Endereços de e-mail do destinatário.
ccRecipients[]

string

Endereços de e-mail do destinatário em Cc.
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 de anexos, preenchidos apenas se MessageFormat for FULL_CONTENT.

Anotações da ferramenta

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