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. The view parameter controls which fields are populated in the related messages. By default (or with THREAD_VIEW_MINIMAL), it includes subject and snippet. Use THREAD_VIEW_METADATA_ONLY to exclude subject and snippet. 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 '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
}'

Input Schema

Request message for SearchThreads RPC.

SearchThreadsRequest

JSON representation 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean

  "view": enum (ThreadView)
}
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:<email> — Sent from a specific person.
  • to:<email> — Sent to a specific person.
  • cc:<email> — Specific people in Cc.
  • bcc:<email> — Specific people in Bcc.
  • deliveredto:<email> — Delivered to a specific address.
  • list:<email> — 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:<duration> — Older than a duration (for example, 1y, 2d).
  • newer_than:<duration> — Newer than a duration.

Content:

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

Labels & Categories:

  • label:<name> — Under a specific label. The tool accepts label IDs, not display names. Use the list_labels tool to get the ID.
  • category:<name> — In a category (primary, social, promotions, updates, forums, reservations, purchases).
  • in:<label> — Search in specific labels (archive, snoozed, trash, sent, inbox). For example, in:trash, in:inbox. Archived and sent messages are included by default; use -in:archive and -in:sent to exclude them. Drafts are explicitly excluded by default by the tool. Use in:inbox to restrict search to the inbox only.
  • has:userlabels — Has any user labels.
  • has:nouserlabels — Does not have any user labels.
  • has:*-star — Specific star colors (if enabled, for example, has:yellow-star).
  • in:draft — Search in drafts. -in:draft means exclude drafts from the search results.
  • in:sent — Search in sent messages.
  • in:anywhere — Search in all folders (including spam and trash).

Status:

  • is:<status> — Search by status (important, starred, unread, read, muted).

Size:

  • size:<bytes> — Specific size in bytes.
  • larger:<size> / smaller:<size> — Larger or smaller than a size (for example, 10M for 10 MB).

Logic & Grouping:

  • AND — Match all criteria (default behavior).
  • OR or { } — Match one or more criteria (for example, from:amy OR from:david, {from:amy from:david}).
  • - (minus) — Exclude criteria (for example, -movie).
  • ( ) — Group multiple search terms (for example, 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 threads from TRASH in the results. Defaults to false.

Union field _view.

_view can be only one of the following:
view

enum (ThreadView)

Optional. Controls the fields populated for threads in the thread list. Defaults to THREAD_VIEW_MINIMAL. THREAD_VIEW_MINIMAL returns id, snippet, subject, from, to, cc, date, labelIds. THREAD_VIEW_METADATA_ONLY returns id, from, to, cc, date, labelIds.

ThreadView

Enum to control the fields populated for threads in the ListThreads and SearchThreads response.

Enums
THREAD_VIEW_UNSPECIFIED Maps to THREAD_VIEW_MINIMAL for backward compatibility.
THREAD_VIEW_METADATA_ONLY Returns id, from, to, cc, date, labelIds.
THREAD_VIEW_MINIMAL Returns id, snippet, subject, from, to, cc, date, labelIds.

Output Schema

Response message for SearchThreads RPC.

SearchThreadsResponse

JSON representation 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": string,
  "resultCountEstimate": 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.
resultCountEstimate

string (int64 format)

The estimated result count for this query. It should be treated as a lower bound, so for example if it is 500, then the count can be reported to the user as "500+".

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