MCP Tools Reference: gmailmcp.googleapis.com

ツール: search_threads

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

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

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

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

入力スキーマ

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

SearchThreadsRequest

JSON 表現 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean

  "view": enum (ThreadView)
}
フィールド

共用体フィールド _page_size。

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

integer

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

共用体フィールド _page_token。

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

string

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

共用体フィールド _query。

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

string

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

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

送信者と受信者:

  • from:<email> - 特定のユーザーから送信されたメール。
  • to:<email> - 特定のユーザーに送信されたアイテム。
  • cc:<email> - Cc の特定のユーザー。
  • bcc:<email> - Bcc に特定のユーザーが含まれている。
  • deliveredto:<email> - 特定の住所に配達済み。
  • list:<email> - 特定のメーリング リストから。

日時:

  • after:YYYY/MM/DD / newer:YYYY/MM/DD - 指定した日付以降に受信したメール。
  • before:YYYY/MM/DD / older:YYYY/MM/DD - 指定した日付より前に受信したメール。
  • older_than:<duration> - 指定した期間より古い（例: 1y、2d）。
  • newer_than:<duration> - 期間よりも新しい。

コンテンツ:

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

ラベルとカテゴリ:

  • label:<name> - 特定のラベルに分類されているメール。このツールでは、表示名ではなくラベル ID を使用します。ID を取得するには、list_labels ツールを使用します。
  • category:<name> - カテゴリ（メイン、ソーシャル、プロモーション、新着、フォーラム、予約、購入）に分類されている。
  • in:<label> - 特定のラベル（アーカイブ、スヌーズ、ゴミ箱、送信済み、受信トレイ）で検索します。例: in:trash、in:inboxアーカイブされたメッセージと送信済みのメッセージはデフォルトで含まれます。これらを除外するには、-in:archive と -in:sent を使用します。下書きは、デフォルトでツールによって明示的に除外されます。in:inbox を使用して、検索対象を受信トレイのみに制限します。
  • has:userlabels - ユーザーラベルがある。
  • has:nouserlabels - ユーザーラベルがありません。
  • has:*-star - 特定の星の色（有効になっている場合、たとえば has:yellow-star）。
  • in:draft - 下書きを検索します。-in:draft は、検索結果から下書きを除外することを意味します。
  • in:sent - 送信済みメールを検索します。
  • in:anywhere - すべてのフォルダ（迷惑メールとゴミ箱を含む）を検索します。

ステータス:

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

サイズ:

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

ロジックとグループ化:

  • AND - すべての条件に一致します（デフォルトの動作）。
  • OR または { } - 1 つ以上の条件（from:amy OR from:david、{from:amy from:david} など）に一致します。
  • -（マイナス） - 条件を除外します（例: -movie）。
  • ( ) - 複数の検索語をグループ化します（例: 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 です。

共用体フィールド _view。

_view は次のいずれかになります。
view

enum (ThreadView)

省略可。スレッド リストのスレッドに入力されるフィールドを制御します。デフォルトは THREAD_VIEW_MINIMAL です。THREAD_VIEW_MINIMAL は、id、snippet、subject、from、to、cc、date、labelIds を返します。THREAD_VIEW_METADATA_ONLY は、id、from、to、cc、date、labelIds を返します。

ThreadView

ListThreads レスポンスと SearchThreads レスポンスでスレッドに入力されるフィールドを制御する列挙型。

列挙型
THREAD_VIEW_UNSPECIFIED 下位互換性のために THREAD_VIEW_MINIMAL にマッピングされます。
THREAD_VIEW_METADATA_ONLY id、from、to、cc、date、labelIds を返します。
THREAD_VIEW_MINIMAL id、snippet、subject、from、to、cc、date、labelIds を返します。

出力スキーマ

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

SearchThreadsResponse

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

object (Thread)

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

string

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

string (int64 format)

このクエリの推定結果数。下限として扱う必要があります。たとえば、500 の場合は、ユーザーに「500+」と報告できます。

スレッド

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
  ],
  "htmlBody": string,
  "attachments": [
    {
      object (AttachmentMetadata)
    }
  ],
  "labelIds": [
    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 の場合にのみ入力されます。
htmlBody

string

メールの HTML コンテンツ。MessageFormat が FULL_CONTENT の場合にのみ入力されます。
attachments[]

object (AttachmentMetadata)

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

string

メッセージに添付されたラベルの ID。ユーザーラベルと標準システムラベルの ID が含まれます。標準システムラベルは INBOX、SPAM、TRASH、UNREAD、STARRED、IMPORTANT、SENT、DRAFT、CHAT に限定されます。

AttachmentMetadata

JSON 表現 
{
  "id": string,
  "mimeType": string,
  "filename": string
}
フィールド
id

string

出力専用。添付ファイルの ID。
mimeType

string

添付ファイルの MIME タイプ。
filename

string

添付ファイルのファイル名。

ツールのアノテーション

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

認可スコープ

次の OAuth スコープのいずれかが必要です。

  • https://mail.google.com/
  • https://www.googleapis.com/auth/gmail.modify
  • https://www.googleapis.com/auth/gmail.readonly