MCP Tools Reference: gmailmcp.googleapis.com

Tool: search_threads

Lists email threads from the authenticated user's Gmail account.

This tool can filter threads based on a query string and supports pagination. It returns a list of threads, including their IDs and related messages. Each related message contains details like a snippet of the message body, the subject, the sender, the recipients etc. Note that the full message bodies are not returned by this tool; use the 'get_thread' tool with a thread ID to fetch the full message body if needed.

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

Curl Request 
curl --location 'https://gmailmcp.googleapis.com/mcp' \
--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 MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

Request message for SearchThreads RPC.

SearchThreadsRequest

JSON representation 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean
}
Fields

Union field _page_size.

_page_size can be only one of the following:
pageSize

integer

Optional. The maximum number of threads to return. If unspecified, defaults to 20. The maximum allowed value is 50.

Union field _page_token.

_page_token can be only one of the following:
pageToken

string

Optional. Page token to retrieve a specific page of results in the list. Leave empty to fetch the first page.

Union field _query.

_query can be only one of the following:
query

string

Optional. A query string to filter the threads, using the same format as the Gmail search bar. If omitted, all threads (excluding spam and trash by default) are listed. Key Operators: from: - Messages from a specific sender. to: - Messages sent to a specific recipient. subject: - Messages with specific words in the subject. - Messages containing specific words in the body or subject. is:unread - Unread messages. is:starred - Starred messages. has:attachment - Messages with attachments. after:YYYY/MM/DD - Messages sent after a date. before:YYYY/MM/DD - Messages sent before a date. newer_than:

 Examples:
 "subject:OneMCP Update"
 "from:gduser1@workspacesamples.dev"
 "to:gduser2@workspacesamples.dev AND newer_than:7d"
 "project proposal has:attachment"
 "is:unread"

Union field _include_trash.

_include_trash can be only one of the following:
includeTrash

boolean

Optional. Include drafts from TRASH in the results. Defaults to false.

Output Schema

Response message for SearchThreads RPC.

SearchThreadsResponse

JSON representation 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": string
}
Fields
threads[]

object (Thread)

List of thread summaries.
nextPageToken

string

A token that can be used in a subsequent call to retrieve the next page of threads. Present only if there are more results.

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

Tool Annotations

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