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. Threads with excluded criteria may still appear in the results. This occurs because Gmail identifies matching messages first. For example, if you search for -is:starred, Gmail will find an entire thread if it contains at least one unstarred message, even if other emails in that same conversation are starred.

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

Curl Request 
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
}'

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. This is primarily used for pagination to continue fetching results from where the previous SearchThreads call left off, especially when the number of threads matching the query exceeds the page_size limit.

Union field _query.

_query can be only one of the following:
query

string

Optional. A query string to filter the threads. Natural language queries must be pre-converted into Gmail syntax queries to use this tool. If omitted, all threads (excluding spam and trash by default) are listed.

Supported Operators by Category:

Sender & Recipient: from: - Sent from a specific person. to: - Sent to a specific person. cc: - Specific people in Cc. bcc: - Specific people in Bcc. deliveredto: - Delivered to a specific address. list: - From a specific mailing list.

Time & Date: after:YYYY/MM/DD / newer:YYYY/MM/DD - Received after a date. before:YYYY/MM/DD / older:YYYY/MM/DD - Received before a date. older_than: - Older than a duration (e.g., 1y, 2d). newer_than: - Newer than a duration.

Content: subject: - Words in the subject line. has: - Has specific content types (attachment, drive, youtube, document). filename: - Attachment with a specific name or type. "<word/phrase>" - Search for an exact word or phrase. (e.g., "holiday", "holiday vacation"). + - Match a word exactly. (e.g., +holiday, +unicorn) rfc822msgid: - Specific message ID header. AROUND - Find words near each other (e.g., holiday AROUND 10 vacation).

Labels & Categories: label: - Under a specific label. The tool accepts label IDs, not display names. Use the list_labels tool to get the ID. category: - In a category (primary, social, promotions, updates, forums, reservations, purchases). in:

Status: is: - Search by status (important, starred, unread, read, muted).

Size: size: - Specific size in bytes. larger: / smaller: - Larger or smaller than a size (e.g., 10M for 10 MB).

Logic & Grouping: AND - Match all criteria (default behavior). OR or { } - Match one or more criteria (e.g., from:amy OR from:david, {from:amy from:david}). - (minus) - Exclude criteria (e.g., -movie). ( ) - Group multiple search terms (e.g., subject:(dinner film)).

Examples: "subject:OneMCP Update" "from:user@example.com" "to:user2@example.com AND newer_than:7d" "project proposal has:attachment" "is:unread -in:draft"

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. If the number of threads matching the query exceeds the page_size limit, the response will contain a next_page_token. To retrieve the next page of results, pass this token in the page_token field of the next SearchThreadsRequest.

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

Tool Annotations

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