MCP Tools Reference: gmailmcp.googleapis.com

ツール: search_threads

認証されたユーザーの Gmail アカウントのメール スレッドを一覧表示します。

このツールは、クエリ文字列に基づいてスレッドをフィルタし、ページネーションをサポートしています。ID や関連するメッセージなど、スレッドのリストが返されます。各関連メッセージには、メッセージ本文の抜粋、件名、送信者、受信者などの詳細が含まれています。このツールではメッセージ本文全体は返されません。必要に応じて、スレッド ID を指定して get_thread ツールを使用し、メッセージ本文全体を取得してください。除外条件に該当するスレッドが結果に表示されることがあります。これは、Gmail で一致するメールが最初に識別されるためです。たとえば、-is:starred を検索すると、スレッドにスターが付いていないメールが 1 つでも含まれていれば、たとえ同じ会話の他のメールにスターが付いていたとしても、そのスレッド全体が結果に表示される場合があります。

次のサンプルは、curl を使用して search_threads MCP ツールを呼び出す方法を示しています。

Curl リクエスト 
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
}'

入力スキーマ

SearchThreads RPC のリクエスト メッセージ。

SearchThreadsRequest

JSON 表現 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean
}
フィールド

共用体フィールド _page_size。

_page_size は次のいずれかになります。
pageSize

integer

省略可。返すスレッドの最大数。指定しない場合のデフォルトは 20 です。最大許容値は 50 です。

共用体フィールド _page_token。

_page_token は次のいずれかになります。
pageToken

string

省略可。リスト内の結果の特定のページを取得するためのページトークン。最初のページを取得するには、空欄のままにします。これは主に、ページ設定に使用され、特にクエリに一致するスレッドの数が page_size の上限を超えた場合に、前の SearchThreads 呼び出しが終了したところから結果の取得を続行します。

共用体フィールド _query。

_query は次のいずれかになります。
query

string

省略可。スレッドをフィルタするクエリ文字列。このツールを使用するには、自然言語クエリを事前に Gmail 構文クエリに変換する必要があります。省略すると、すべてのスレッド（デフォルトではスパムとゴミ箱を除く）が一覧表示されます。

カテゴリ別のサポートされている演算子:

送信者と受信者: from: - 特定のユーザーから送信された。to: - 特定のユーザーに送信されたメール。cc: - Cc の特定のユーザー。bcc: - Bcc の特定のユーザー。deliveredto: - 特定の住所に配達された。list: - 特定のメーリング リストから。

Time & Date: after:YYYY/MM/DD / newer:YYYY/MM/DD - Received after a date. before:YYYY/MM/DD / older:YYYY/MM/DD - 特定の日付より前に受信したメール。older_than: - 指定した期間より古い（例: 1 年、2 日）。newer_than: - 指定した期間より新しい。

コンテンツ: subject: - 件名に含まれる単語。 has: - 特定のコンテンツ タイプ（添付ファイル、ドライブ、YouTube、ドキュメント）がある。filename: - 特定の名前または種類の添付ファイル。"<単語/フレーズ>" - 指定した単語やフレーズとの完全一致を検索します。（例: 「休日」、「休暇」）。+ - 単語を完全に一致させます。（例: +holiday、+unicorn） rfc822msgid: - 特定のメッセージ ID ヘッダー。AROUND - 近くにある 2 つの単語を検索する（例: holiday AROUND 10 vacation）。

ラベルとカテゴリ: label: - 特定のラベルに分類されている。このツールでは、表示名ではなくラベル ID を使用します。ID を取得するには、list_labels ツールを使用します。category: - カテゴリ（メイン、ソーシャル、プロモーション、新着、フォーラム、予約、購入）に分類されている。in:

ステータス: is: - ステータス（重要、スター付き、未読、既読、ミュート）で検索します。

サイズ: size: - バイト単位の特定のサイズ。larger: / smaller: - サイズより大きいか小さいか（例: 10M は 10 MB）。

論理とグループ化: AND - すべての条件に一致します（デフォルトの動作）。OR または { } - 1 つ以上の条件に一致します（例: from:amy OR from:david、{from:amy from:david}）。-（マイナス）- 条件を除外します（例: -映画）。( ) - 複数の検索語をグループ化します（例: subject:(dinner film)）。

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

共用体フィールド _include_trash。

_include_trash は次のいずれかになります。
includeTrash

boolean

省略可。ゴミ箱のドラフトを結果に含めます。デフォルトは false です。

出力スキーマ

SearchThreads RPC のレスポンス メッセージ。

SearchThreadsResponse

JSON 表現 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": string
}
フィールド
threads[]

object (Thread)

スレッドの概要のリスト。
nextPageToken

string

後続の呼び出しでスレッドの次のページを取得するために使用できるトークン。結果が複数ある場合にのみ存在します。クエリに一致するスレッドの数が page_size の上限を超えると、レスポンスに next_page_token が含まれます。結果の次のページを取得するには、次の SearchThreadsRequest の page_token フィールドでこのトークンを渡します。

スレッド

JSON 表現 
{
  "id": string,
  "messages": [
    {
      object (Message)
    }
  ]
}
フィールド
id

string

スレッドの一意の識別子。
messages[]

object (Message)

スレッド内のメッセージのリスト（時系列順）。

メッセージ

JSON 表現 
{
  "id": string,
  "snippet": string,
  "subject": string,
  "sender": string,
  "toRecipients": [
    string
  ],
  "ccRecipients": [
    string
  ],
  "date": string,
  "plaintextBody": string,
  "attachmentIds": [
    string
  ]
}
フィールド
id

string

メッセージの一意の識別子。
snippet

string

メッセージ本文のスニペット。
subject

string

ヘッダーから抽出されたメッセージの件名:
sender

string

送信者のメールアドレス。
toRecipients[]

string

受信者のメールアドレス。
ccRecipients[]

string

Cc 受信者のメールアドレス。
date

string

メッセージの日付（ISO 8601 形式（YYYY-MM-DD））。
plaintextBody

string

本文のコンテンツ全体。MessageFormat が FULL_CONTENT の場合にのみ設定されます。
attachmentIds[]

string

出力専用。添付ファイルの ID。MessageFormat が FULL_CONTENT の場合にのみ入力されます。

ツールのアノテーション

破壊的ヒント: ❌ | べき等ヒント: ✅ | 読み取り専用ヒント: ✅ | オープン ワールド ヒント: ❌