MCP Tools Reference: gmailmcp.googleapis.com

Tool: get_thread

Retrieves a specific email thread from the authenticated user's Gmail account, including a list of its messages.

The optional messageFormat parameter controls the format of the messages returned. By default (or with FULL_CONTENT), it returns the full content of messages. Use MINIMAL to include only subject and snippet (excluding body). Use METADATA_ONLY to include only basic metadata (message ID, thread ID, labels, timestamp, and size estimate).

The following sample demonstrate how to use curl to invoke the get_thread MCP tool.

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

Input Schema

Request message for GetThread RPC.

GetThreadRequest

JSON representation 
{
  "threadId": string,
  "messageFormat": enum (MessageFormat)
}
Fields
threadId

string

Required. The unique identifier of the thread to fetch.
messageFormat

enum (MessageFormat)

Optional. Specifies the format of the messages returned within the thread. Defaults to FULL_CONTENT. Note: MINIMAL format returns id, snippet, subject, from, to, cc, date, labelIds. METADATA_ONLY format returns id, from, to, cc, date, labelIds. FULL_CONTENT returns id, snippet, subject, from, to, cc, date, labelIds, attachmentIds, plaintextBody, htmlBody, attachments.

MessageFormat

Enum to control the level of detail for messages in the thread.

Enums
MESSAGE_FORMAT_UNSPECIFIED Defaults to FULL_CONTENT.
MINIMAL Returns message snippets and key headers (Subject, From, To, Cc, Date).
FULL_CONTENT Returns all information in "MINIMAL" plus the full body content of each message.
METADATA_ONLY Metadata only: does not include subject, snippet, body, attachment filenames.

Output Schema

Thread containing a list of messages.

Thread

JSON representation 
{
  "id": string,
  "messages": [
    {
      object (Message)
    }
  ]
}
Fields
id

string

The unique identifier of the thread.
messages[]

object (Message)

A list of messages in the thread, ordered chronologically.

Message

JSON representation 
{
  "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
  ]
}
Fields
id

string

The unique identifier of the message.
snippet

string

Snippet of the message body.
subject

string

The message subject extracted from headers:
sender

string

Sender email address.
toRecipients[]

string

To recipient email addresses.
ccRecipients[]

string

CC recipient email addresses.
date

string

Date of the message in ISO 8601 format (YYYY-MM-DD).
plaintextBody

string

Full body content, only populated if MessageFormat was FULL_CONTENT.
attachmentIds[]

string

Output only. The attachment ids, only populated if MessageFormat was FULL_CONTENT.
htmlBody

string

The HTML content of the email, only populated if MessageFormat was FULL_CONTENT.
attachments[]

object (AttachmentMetadata)

Output only. The attachments, only populated if MessageFormat was FULL_CONTENT.
labelIds[]

string

The ids of the labels attached to the message. Includes ids of user labels and standard system labels limited to INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, SENT, DRAFT, CHAT.

AttachmentMetadata

JSON representation 
{
  "id": string,
  "mimeType": string,
  "filename": string
}
Fields
id

string

Output only. The ID of the attachment.
mimeType

string

The MIME type of the attachment.
filename

string

The filename of the attachment.

Tool Annotations

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌

Authorization Scopes

Requires one of the following OAuth scopes:

  • 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