MCP Tools Reference: gmailmcp.googleapis.com

Herramienta: get_message

Recupera un mensaje de correo electrónico específico de la cuenta de Gmail del usuario autenticado por su ID de mensaje único.

Usa esta herramienta para inspeccionar un solo correo electrónico individual cuando ya conoces su ID de mensaje. Si el usuario quiere leer un correo electrónico específico en detalle, verificar la redacción exacta de un mensaje o examinar los metadatos adjuntos de un solo correo electrónico, esta es la herramienta adecuada. No es adecuada para recuperar conversaciones completas ni ver conversaciones de ida y vuelta. En su lugar, usa la herramienta "get_thread". Los indicadores clave incluyen si el usuario solicita el contenido completo de un ID de mensaje específico que se muestra en una búsqueda anterior o si la consulta solicita inspeccionar un correo electrónico individual específico en lugar de una conversación completa. Algunos ejemplos de mensajes del usuario son: "Obtén el texto completo del ID de mensaje 18f123456789abcd", "Lee el mensaje más reciente de esa conversación de Alice" y "¿Cuáles son los nombres de los archivos adjuntos en el correo electrónico que acabo de recibir de RR.HH.?".

El parámetro messageFormat opcional controla el formato del mensaje que se muestra. De forma predeterminada (o con FULL_CONTENT), muestra el contenido completo del mensaje. Usa MINIMAL para incluir solo el asunto y el fragmento (sin incluir el cuerpo). Usa METADATA_ONLY para incluir solo metadatos básicos (ID de mensaje, ID de conversación, etiquetas, marca de tiempo y estimación de tamaño).

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

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": "get_message",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Esquema de entrada

Mensaje de solicitud para GetMessage RPC.

GetMessageRequest

Representación JSON 
{
  "messageId": string,
  "messageFormat": enum (MessageFormat)
}
Campos
messageId

string

Obligatorio. El identificador único del mensaje que se recuperará.
messageFormat

enum (MessageFormat)

Es opcional. Especifica el formato del mensaje que se muestra. La configuración predeterminada es FULL_CONTENT.

MessageFormat

Enum para controlar el nivel de detalle de los mensajes en la conversación.

Enums
MESSAGE_FORMAT_UNSPECIFIED La configuración predeterminada es FULL_CONTENT.
MINIMAL Muestra fragmentos de mensajes y encabezados clave (asunto, de, para, cc, fecha).
FULL_CONTENT Muestra toda la información en "MINIMAL" más el contenido completo del cuerpo de cada mensaje.
METADATA_ONLY Solo metadatos: no incluye asunto, fragmento, cuerpo ni nombres de archivos adjuntos.

Esquema de salida

Mensaje dentro de una conversación.

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

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 del destinatario
ccRecipients[]

string

Direcciones de correo electrónico del destinatario de 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.
htmlBody

string

El contenido HTML del correo electrónico, solo propagado si MessageFormat era FULL_CONTENT.
attachments[]

object (AttachmentMetadata)

Solo salida. Los archivos adjuntos, solo propagados si MessageFormat era FULL_CONTENT.
labelIds[]

string

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

AttachmentMetadata

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

string

Solo salida. El ID del archivo adjunto.
mimeType

string

El tipo de MIME del archivo adjunto.
filename

string

El 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
  • https://www.googleapis.com/auth/gmail.metadata