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: ❌
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: