MCP Tools Reference: gmailmcp.googleapis.com

Herramienta: search_threads

Muestra las conversaciones de correo electrónico de la cuenta de Gmail del usuario autenticado.

Esta herramienta puede filtrar conversaciones en función de una cadena de consulta y admite la paginación. Muestra una lista de conversaciones, incluidos sus IDs y mensajes relacionados. Cada mensaje relacionado contiene detalles como un fragmento del cuerpo del mensaje, el asunto, el remitente, los destinatarios, etcétera. Ten en cuenta que esta herramienta no muestra los cuerpos completos de los mensajes. Si es necesario, usa la herramienta "get_thread" con un ID de conversación para obtener el cuerpo completo del mensaje. Es posible que las conversaciones con criterios excluidos aún aparezcan en los resultados. Esto sucede porque Gmail identifica primero los mensajes coincidentes. Por ejemplo, si buscas -is:starred, Gmail encontrará una conversación completa si contiene al menos un mensaje sin destacar, incluso si otros correos electrónicos de esa misma conversación están destacados.

En el siguiente ejemplo, se muestra cómo usar curl para invocar la herramienta MCP search_threads.

Solicitud 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

Mensaje de solicitud para SearchThreads RPC.

SearchThreadsRequest

Representación JSON 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean
}
Campos

Campo de unión _page_size.

_page_size puede ser una de las siguientes opciones:
pageSize

integer

Es opcional. Es la cantidad máxima de conversaciones que se devolverán. Si no se especifica, se establece de forma predeterminada como 20. El valor máximo permitido es 50.

Campo de unión _page_token.

_page_token puede ser una de las siguientes opciones:
pageToken

string

Es opcional. Es el token de página para recuperar una página específica de resultados en la lista. Déjalo vacío para obtener la primera página. Se usa principalmente para la paginación para seguir recuperando resultados desde donde se detuvo la llamada SearchThreads anterior, en especial, cuando la cantidad de conversaciones que coinciden con la consulta supera el límite de page_size.

Campo de unión _query.

_query puede ser una de las siguientes opciones:
query

string

Es opcional. Es una cadena de consulta para filtrar las conversaciones. Las consultas en lenguaje natural deben convertirse previamente en consultas de sintaxis de Gmail para usar esta herramienta. Si se omite, se muestran todas las conversaciones (excepto el spam y la papelera de forma predeterminada).

Operadores admitidos por categoría:

Remitente y destinatario: from: - Se envió desde una persona específica. to: - Se envió a una persona específica. cc: - Personas específicas en Cc. bcc: - Personas específicas en Cco. deliveredto: - Se entregó a una dirección específica. list: - De una lista de distribución específica.

Hora y fecha: after:AAAA/MM/DD / newer:AAAA/MM/DD - Se recibió después de una fecha. before:AAAA/MM/DD / older:AAAA/MM/DD - Se recibió antes de una fecha. older_than: - Más antiguo que una duración (p.ej., 1a, 2d). newer_than: - Más reciente que una duración.

Contenido: subject: - Determinadas palabras en el asunto. has: - Tiene tipos de contenido específicos (adjunto, Drive, YouTube, documento). filename: - Adjunto con un nombre o tipo específico. "<palabra/frase>" - Una palabra o frase exacta. (p.ej., "vacaciones", "vacaciones de descanso"). + - Coincide exactamente con una palabra. (p.ej., +vacaciones, +unicornio) rfc822msgid: - Encabezado de ID de mensaje específico. AROUND - Busca palabras cercanas entre sí (p.ej., vacaciones AROUND 10 descanso).

Etiquetas y categorías: label: - Con una etiqueta específica. La herramienta acepta IDs de etiquetas, no nombres para mostrar. Usa la herramienta list_labels para obtener el ID. category: - En una categoría (principal, social, promociones, notificaciones, foros, reservas, compras). in:

Estado: is: - Busca por estado (importante, destacado, sin leer, leído, silenciado).

Tamaño: size: - Tamaño específico en bytes. larger: / smaller: - Más grande o más pequeño que un tamaño (p.ej., 10M para 10 MB).

Lógica y agrupación: AND - Coincide con todos los criterios (comportamiento predeterminado). OR o { } - Coincide con uno o más criterios (p.ej., from:amy OR from:david, {from:amy from:david}). - (menos) - Excluye criterios (p.ej., -película). ( ) - Agrupa varios términos de búsqueda (p.ej., subject:(cena película)).

Ejemplos: "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ón _include_trash.

_include_trash puede ser una de las siguientes opciones:
includeTrash

boolean

Es opcional. Incluye borradores de la PAPELERA en los resultados. La configuración predeterminada es "false".

Esquema de salida

Mensaje de respuesta para SearchThreads RPC.

SearchThreadsResponse

Representación JSON 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": string
}
Campos
threads[]

object (Thread)

Lista de resúmenes de conversaciones.
nextPageToken

string

Un token que se puede usar en una llamada posterior para recuperar la siguiente página de conversaciones. Solo está presente si hay más resultados. Si la cantidad de conversaciones que coinciden con la consulta supera el límite de page_size, la respuesta contendrá un next_page_token. Para recuperar la siguiente página de resultados, pasa este token en el campo page_token del siguiente SearchThreadsRequest.

Conversación

Representación JSON 
{
  "id": string,
  "messages": [
    {
      object (Message)
    }
  ]
}
Campos
id

string

El identificador único de la conversación.
messages[]

object (Message)

Una lista de mensajes en la conversación, ordenados cronológicamente.

Mensaje

Representación JSON 
{
  "id": string,
  "snippet": string,
  "subject": string,
  "sender": string,
  "toRecipients": [
    string
  ],
  "ccRecipients": [
    string
  ],
  "date": string,
  "plaintextBody": string,
  "attachmentIds": [
    string
  ]
}
Campos
id

string

El identificador único del mensaje.
snippet

string

Fragmento del cuerpo del mensaje.
subject

string

El asunto del mensaje extraído de los encabezados:
sender

string

Dirección de correo electrónico del remitente
toRecipients[]

string

Direcciones de correo electrónico de los destinatarios
ccRecipients[]

string

Direcciones de correo electrónico de los destinatarios en CC
date

string

Fecha del mensaje en formato ISO 8601 (AAAA-MM-DD)
plaintextBody

string

Contenido completo del cuerpo, solo propagado si MessageFormat era FULL_CONTENT
attachmentIds[]

string

Solo salida. Los IDs de los archivos adjuntos, solo propagados si MessageFormat era FULL_CONTENT

Anotaciones de herramientas

Sugerencia destructiva: ❌ | Sugerencia idempotente: ✅ | Sugerencia de solo lectura: ✅ | Sugerencia de mundo abierto: ❌