MCP Tools Reference: gmailmcp.googleapis.com

Инструмент: search_threads

Отображает переписку по электронной почте из учетной записи Gmail авторизованного пользователя.

Этот инструмент позволяет фильтровать ветки обсуждений на основе строки запроса и поддерживает пагинацию. Он возвращает список веток, включая их идентификаторы и связанные сообщения. Каждое связанное сообщение содержит подробную информацию, такую ​​как фрагмент текста сообщения, тема, отправитель, получатели и т. д. Параметр view управляет тем, какие поля заполняются в связанных сообщениях. По умолчанию (или с THREAD_VIEW_MINIMAL ) он включает тему и фрагмент текста. Используйте THREAD_VIEW_METADATA_ONLY , чтобы исключить тему и фрагмент текста. Обратите внимание, что полные тексты сообщений не возвращаются этим инструментом; при необходимости используйте инструмент 'get_thread' с идентификатором ветки, чтобы получить полный текст сообщения. Ветки с исключенными критериями все еще могут отображаться в результатах. Это происходит потому, что Gmail сначала идентифицирует соответствующие сообщения. Например, если вы выполните поиск по запросу -is:starred, Gmail найдет всю ветку, если она содержит хотя бы одно сообщение без звездочки, даже если другие письма в той же беседе отмечены звездочкой.

В следующем примере показано, как использовать curl для вызова инструмента MCP search_threads .

Запрос 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
}'

Схема ввода

Сообщение запроса для RPC-вызова SearchThreads.

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

Необязательный параметр. Токен страницы для получения конкретной страницы результатов в списке. Оставьте поле пустым, чтобы получить первую страницу. Он в основном используется для пагинации, чтобы продолжить получение результатов с того места, где остановился предыдущий вызов SearchThreads , особенно когда количество потоков, соответствующих запросу, превышает лимит page_size.

Объединение полей _query .

_query может принимать только одно из следующих значений:

query

string

Необязательно. Строка запроса для фильтрации цепочек сообщений. Запросы на естественном языке должны быть предварительно преобразованы в синтаксис Gmail для использования этого инструмента. Если этот параметр опущен, отображаются все цепочки сообщений (по умолчанию исключая спам и корзину).

Поддерживаемые операторы по категориям:

Отправитель и получатель:

  • from:<email> — Отправлено конкретным человеком.
  • to:<email> — Отправлено конкретному лицу.
  • cc:<email> — Конкретные лица в Cc.
  • bcc:<email> — В скрытой копии указаны конкретные люди.
  • 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> — Заголовок с конкретным идентификатором сообщения.
  • AROUND <distance> — Найдите слова, расположенные близко друг к другу (например, holiday AROUND 10 vacation ).

Метки и категории:

  • label:<name> — Под определенной меткой. Инструмент принимает идентификаторы меток, а не отображаемые имена. Используйте инструмент 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 или { } — Соответствует одному или нескольким критериям (например, 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.

Union _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

Перечисление (Enum) для управления полями, заполняемыми для потоков в ответах 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.

Схема вывода

Ответное сообщение для RPC-запроса SearchThreads.

SearchThreadsResponse

JSON-представление 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": string,
  "resultCountEstimate": string
}
Поля
threads[]

object ( Thread )

Список кратких описаний тем обсуждения.

nextPageToken

string

Токен, который можно использовать в последующем вызове для получения следующей страницы обсуждений. Присутствует только в том случае, если есть дополнительные результаты. Если количество обсуждений, соответствующих запросу, превышает лимит page_size, ответ будет содержать next_page_token . Чтобы получить следующую страницу результатов, передайте этот токен в поле page_token следующего SearchThreadsRequest .

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

Адреса электронной почты получателей копии.

date

string

Дата сообщения в формате ISO 8601 (ГГГГ-ММ-ДД).

plaintextBody

string

Полное содержимое тела сообщения, заполняется только в том случае, если MessageFormat имеет значение FULL_CONTENT.

attachmentIds[]

string

Только для вывода. Идентификаторы вложений заполняются только в том случае, если MessageFormat имеет значение FULL_CONTENT.

htmlBody

string

HTML-содержимое электронного письма, заполняемое только в том случае, если MessageFormat имеет значение FULL_CONTENT.

attachments[]

object ( AttachmentMetadata )

Только вывод. Вложения заполняются только в том случае, если MessageFormat имеет значение FULL_CONTENT.

labelIds[]

string

Идентификаторы меток, прикрепленных к сообщению. Включает идентификаторы пользовательских меток и стандартных системных меток, ограниченных следующими: INBOX , SPAM , TRASH , UNREAD , STARRED , IMPORTANT , SENT , DRAFT , CHAT .

Метаданные вложения

JSON-представление 
{
  "id": string,
  "mimeType": string,
  "filename": string
}
Поля
id

string

Только вывод. Идентификатор вложения.

mimeType

string

MIME-тип вложения.

filename

string

Имя файла вложения.

Аннотации инструментов

Подсказка о разрушительном эффекте: ❌ | Подсказка об идемпотентности: ✅ | Подсказка только для чтения: ✅ | Подсказка об открытом мире: ❌

Области полномочий

Требуется один из следующих диапазонов аутентификации OAuth:

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