MCP Tools Reference: gmailmcp.googleapis.com

Herramienta: search_threads

Enumera los subprocesos de correo electrónico de la cuenta de Gmail del usuario autenticado.

Esta herramienta puede filtrar subprocesos según una cadena de consulta y admite la paginación. Devuelve una lista de conversaciones, incluidos sus IDs y los mensajes relacionados. Cada mensaje relacionado contiene detalles como un fragmento del cuerpo del mensaje, el asunto, el remitente, los destinatarios, etcétera. El parámetro view controla qué campos se completan en los mensajes relacionados. De forma predeterminada (o con THREAD_VIEW_MINIMAL), incluye el asunto y el fragmento. Usa THREAD_VIEW_METADATA_ONLY para excluir el asunto y el fragmento. Ten en cuenta que esta herramienta no devuelve los cuerpos completos de los mensajes. Si es necesario, usa la herramienta "get_thread" con un ID de conversación para recuperar el cuerpo completo del mensaje. Es posible que los hilos con criterios excluidos sigan apareciendo en los resultados. Esto sucede porque Gmail identifica primero los mensajes coincidentes. Por ejemplo, si buscas -is:starred, Gmail encontrará un hilo completo 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 de MCP search_threads.

Solicitud de 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

Es el mensaje de solicitud para la RPC de SearchThreads.

SearchThreadsRequest

Representación JSON 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean

  "view": enum (ThreadView)
}
Campos

Campo de unión _page_size.

_page_size puede ser una de las siguientes opciones:
pageSize

integer

Opcional. Es la cantidad máxima de subprocesos que se devolverán. Si no se especifica, el valor predeterminado es 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

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 y para seguir recuperando resultados desde donde se detuvo la llamada anterior a SearchThreads, en especial cuando la cantidad de subprocesos que coinciden con la búsqueda supera el límite de page_size.

Campo de unión _query.

_query puede ser una de las siguientes opciones:
query

string

Opcional. Es una cadena de consulta para filtrar los subprocesos. Para usar esta herramienta, las consultas en lenguaje natural se deben convertir previamente en consultas de sintaxis de Gmail. Si se omite, se mostrarán todos los subprocesos (excepto los de spam y papelera de forma predeterminada).

Operadores admitidos por categoría:

Remitente y destinatario:

  • from:<email>: Se envió desde una persona específica.
  • to:<email>: Se envió a una persona específica.
  • cc:<email>: Personas específicas en Cc.
  • bcc:<email>: Personas específicas en Cco.
  • deliveredto:<email>: Se entregó en una dirección específica.
  • list:<email>: De una lista de distribución específica

Fecha y hora:

  • after:YYYY/MM/DD / newer:YYYY/MM/DD: Se recibió después de una fecha.
  • before:YYYY/MM/DD / older:YYYY/MM/DD: Se recibió antes de una fecha.
  • older_than:<duration>: Es anterior a una duración (por ejemplo, 1y, 2d).
  • newer_than:<duration>: Es más reciente que una duración.

Contenido:

  • subject:<words>: Palabras en el asunto
  • has:<type>: Tiene tipos de contenido específicos (archivo adjunto, Drive, YouTube, documento).
  • filename:<name>: Es un archivo adjunto con un nombre o tipo específico.
  • "<word/phrase>": Busca una palabra o frase exacta. (por ejemplo, "holiday", "holiday vacation")
  • +<word>: Coincide exactamente con una palabra. (por ejemplo, +holiday, +unicorn)
  • rfc822msgid:<id>: Es el encabezado de ID de mensaje específico.
  • AROUND <distance>: Encuentra palabras cercanas entre sí (por ejemplo, holiday AROUND 10 vacation).

Etiquetas y categorías:

  • label:<name>: Con una etiqueta específica La herramienta acepta IDs de etiquetas, no nombres visibles. Usa la herramienta list_labels para obtener el ID.
  • category:<name>: En una categoría (principal, social, promociones, actualizaciones, foros, reservas, compras)
  • in:<label>: Busca en etiquetas específicas (archivo, pospuestos, papelera, enviados, recibidos). Por ejemplo: in:trash, in:inbox. Los mensajes archivados y enviados se incluyen de forma predeterminada. Usa -in:archive y -in:sent para excluirlos. De forma predeterminada, la herramienta excluye explícitamente los borradores. Usa in:inbox para restringir la búsqueda solo a la carpeta Recibidos.
  • has:userlabels: Tiene etiquetas de usuario.
  • has:nouserlabels: No tiene etiquetas de usuario.
  • has:*-star: Colores de estrellas específicos (si está habilitado, por ejemplo, has:yellow-star).
  • in:draft: Busca en los borradores. -in:draft significa que se excluyen los borradores de los resultados de la búsqueda.
  • in:sent: Busca en los mensajes enviados.
  • in:anywhere: Busca en todas las carpetas (incluidas Spam y Papelera).

Estado:

  • is:<status>: Busca por estado (importante, destacado, no leído, leído o silenciado).

Tamaño:

  • size:<bytes>: Tamaño específico en bytes.
  • larger:<size> o smaller:<size>: Mayor o menor que un tamaño (por ejemplo, 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 (por ejemplo, from:amy OR from:david, {from:amy from:david}).
  • - (menos): Excluye criterios (por ejemplo, -movie).
  • ( ): Agrupa varios términos de búsqueda (por ejemplo, subject:(dinner film)).

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

Opcional. Incluye los hilos de la PAPELERA en los resultados. La configuración predeterminada es "false".

Campo de unión _view.

_view puede ser una de las siguientes opciones:
view

enum (ThreadView)

Opcional. Controla los campos que se completan para los subprocesos en la lista de subprocesos. La configuración predeterminada es THREAD_VIEW_MINIMAL. THREAD_VIEW_MINIMAL devuelve id, fragmento, asunto, de, para, cc, fecha y labelIds. THREAD_VIEW_METADATA_ONLY devuelve id, from, to, cc, date y labelIds.

ThreadView

Es una enumeración para controlar los campos que se propagan para los subprocesos en las respuestas de ListThreads y SearchThreads.

Enums
THREAD_VIEW_UNSPECIFIED Se asigna a THREAD_VIEW_MINIMAL para la retrocompatibilidad.
THREAD_VIEW_METADATA_ONLY Devuelve id, from, to, cc, date y labelIds.
THREAD_VIEW_MINIMAL Devuelve id, fragmento, asunto, de, para, cc, fecha y labelIds.

Esquema de salida

Es el mensaje de respuesta para la RPC de SearchThreads.

SearchThreadsResponse

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

object (Thread)

Lista de resúmenes de conversaciones.
nextPageToken

string

Es un token que se puede usar en una llamada posterior para recuperar la siguiente página de subprocesos. Solo está presente si hay más resultados. Si la cantidad de subprocesos que coinciden con la búsqueda 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.
resultCountEstimate

string (int64 format)

Es el recuento de resultados estimado para esta búsqueda. Se debe tratar como un límite inferior, por lo que, por ejemplo, si es 500, el recuento se puede informar al usuario como "más de 500".

Thread

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

string

Es el identificador único del subproceso.
messages[]

object (Message)

Es una lista de mensajes del debate, 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
  ],
  "htmlBody": string,
  "attachments": [
    {
      object (AttachmentMetadata)
    }
  ],
  "labelIds": [
    string
  ]
}
Campos
id

string

Es el identificador único del mensaje.
snippet

string

Es el fragmento del cuerpo del mensaje.
subject

string

Asunto del mensaje extraído de los encabezados:
sender

string

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

string

A las direcciones de correo electrónico de los destinatarios
ccRecipients[]

string

Son las direcciones de correo electrónico de los destinatarios en Cc.
date

string

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

string

Es el contenido completo del cuerpo, que solo se propaga si MessageFormat era FULL_CONTENT.
attachmentIds[]

string

Solo salida. Son los IDs de los archivos adjuntos, que solo se propagan si MessageFormat era FULL_CONTENT.
htmlBody

string

Es el contenido HTML del correo electrónico, que solo se propaga si MessageFormat era FULL_CONTENT.
attachments[]

object (AttachmentMetadata)

Solo salida. Son los archivos adjuntos, que solo se propagan si MessageFormat era FULL_CONTENT.
labelIds[]

string

Son los IDs de las etiquetas adjuntas al mensaje. Incluye los IDs de las etiquetas del usuario y las etiquetas estándar del sistema limitadas a INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, SENT, DRAFT, CHAT.

AttachmentMetadata

Representación JSON 
{
  "id": string,
  "mimeType": string,
  "filename": string
}
Campos
id

string

Solo salida. Es el ID del adjunto.
mimeType

string

Tipo de MIME del archivo adjunto.
filename

string

Nombre del archivo adjunto.

Anotaciones de herramientas

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

Alcances de la autorización

Se necesita uno de los siguientes alcances de OAuth:

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