MCP Tools Reference: gmailmcp.googleapis.com

Narzędzie: search_threads

Wyświetla wątki e-maili z konta Gmail uwierzytelnionego użytkownika.

To narzędzie może filtrować wątki na podstawie ciągu zapytania i obsługuje paginację. Zwraca listę wątków, w tym ich identyfikatory i powiązane wiadomości. Każda powiązana wiadomość zawiera szczegóły, takie jak fragment treści wiadomości, temat, nadawca, odbiorcy itp. Parametr view określa, które pola są wypełniane w powiązanych wiadomościach. Domyślnie (lub w przypadku THREAD_VIEW_MINIMAL) zawiera temat i krótki opis. Użyj THREAD_VIEW_METADATA_ONLY, aby wykluczyć temat i fragment. Pamiętaj, że to narzędzie nie zwraca pełnych treści wiadomości. Jeśli potrzebujesz pełnej treści wiadomości, użyj narzędzia „get_thread” z identyfikatorem wątku. W wynikach mogą się nadal wyświetlać wątki zawierające wykluczone elementy. Dzieje się tak, ponieważ Gmail najpierw identyfikuje pasujące wiadomości. Jeśli na przykład wyszukasz -is:starred, Gmail znajdzie cały wątek, jeśli zawiera on co najmniej 1 wiadomość bez gwiazdki, nawet jeśli inne e-maile w tej samej rozmowie są oznaczone gwiazdką.

Poniższy przykład pokazuje, jak za pomocą curl wywołać narzędzie search_threads MCP.

Żądanie 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
}'

Schemat danych wejściowych

Wiadomość z prośbą o wywołanie RPC SearchThreads.

SearchThreadsRequest

Zapis JSON 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean

  "view": enum (ThreadView)
}
Pola

Pole zbiorcze _page_size.

Pole _page_size może mieć tylko jedną z tych wartości:
pageSize

integer

Opcjonalnie. Maksymalna liczba wątków do zwrócenia. Jeśli nie podasz żadnej wartości, domyślnie zostanie użyta wartość 20. Maksymalna dozwolona wartość to 50.

Pole zbiorcze _page_token.

Pole _page_token może mieć tylko jedną z tych wartości:
pageToken

string

Opcjonalnie. Token strony umożliwiający pobranie konkretnej strony wyników na liście. Aby pobrać pierwszą stronę, pozostaw to pole puste. Jest to używane głównie w przypadku podziału na strony, aby kontynuować pobieranie wyników od miejsca, w którym zakończyło się poprzednie wywołanie SearchThreads, zwłaszcza gdy liczba wątków pasujących do zapytania przekracza limit page_size.

Pole zbiorcze _query.

Pole _query może mieć tylko jedną z tych wartości:
query

string

Opcjonalnie. Ciąg zapytania do filtrowania wątków. Aby korzystać z tego narzędzia, zapytania w języku naturalnym muszą być wcześniej przekonwertowane na zapytania w składni Gmaila. Jeśli ten parametr zostanie pominięty, wyświetlone zostaną wszystkie wątki (z wyjątkiem spamu i kosza).

Obsługiwane operatory według kategorii:

Nadawca i odbiorca:

  • from:<email> – wysłane przez konkretną osobę.
  • to:<email> – wysłane do konkretnej osoby.
  • cc:<email> – określone osoby w polu DW.
  • bcc:<email> – określone osoby w polu UDW.
  • deliveredto:<email> – dostarczono na konkretny adres.
  • list:<email> – z określonej listy adresowej.

Godzina i data:

  • after:YYYY/MM/DD / newer:YYYY/MM/DD – otrzymano po określonej dacie.
  • before:YYYY/MM/DD / older:YYYY/MM/DD – otrzymano przed datą.
  • older_than:<duration> – starsze niż określony czas (np. 1y, 2d).
  • newer_than:<duration> – nowsze niż określony czas trwania.

Treść:

  • subject:<words> – słowa w temacie.
  • has:<type> – zawiera określone typy treści (załącznik, Dysk, YouTube, dokument).
  • filename:<name> – załącznik o określonej nazwie lub określonego typu.
  • "<word/phrase>" – wyszukiwanie dokładnego słowa lub wyrażenia. (na przykład "holiday", "holiday vacation").
  • +<word> – dopasowanie dokładne słowa. (np. +holiday, +unicorn)
  • rfc822msgid:<id> – nagłówek z identyfikatorem konkretnej wiadomości.
  • AROUND <distance> – wyszukiwanie słów blisko siebie (np. holiday AROUND 10 vacation).

Etykiety i kategorie:

  • label:<name> – z określoną etykietą. Narzędzie akceptuje identyfikatory etykiet, a nie nazwy wyświetlane. Aby uzyskać identyfikator, użyj narzędzia list_labels.
  • category:<name> – w kategorii (główne, społeczności, oferty, powiadomienia, fora, rezerwacje, zakupy);
  • in:<label> – wyszukiwanie w określonych etykietach (archiwum, odłożone, kosz, wysłane, odebrane). Na przykład: in:trash, in:inbox. Zarchiwizowane i wysłane wiadomości są domyślnie uwzględniane. Aby je wykluczyć, użyj symboli -in:archive i -in:sent. Narzędzie domyślnie wyklucza wersje robocze. Użyj in:inbox, aby ograniczyć wyszukiwanie tylko do skrzynki odbiorczej.
  • has:userlabels – ma etykiety użytkownika.
  • has:nouserlabels – nie ma żadnych etykiet użytkowników.
  • has:*-star – konkretne kolory gwiazdek (jeśli są włączone, np. has:yellow-star).
  • in:draft – wyszukiwanie w wersjach roboczych. -in:draft oznacza wykluczenie wersji roboczych z wyników wyszukiwania.
  • in:sent – wyszukiwanie w wysłanych wiadomościach.
  • in:anywhere – wyszukiwanie we wszystkich folderach (w tym w Spamie i Koszu).

Stan:

  • is:<status> – wyszukiwanie według stanu (ważne, oznaczone gwiazdką, nieprzeczytane, przeczytane, wyciszone).

Rozmiar:

  • size:<bytes> – konkretny rozmiar w bajtach.
  • larger:<size> / smaller:<size> – większy lub mniejszy niż określony rozmiar (np. 10M dla 10 MB).

Logika i grupowanie:

  • AND – dopasuj wszystkie kryteria (domyślne działanie).
  • OR lub { } – dopasowanie do co najmniej 1 kryterium (np. from:amy OR from:david, {from:amy from:david}).
  • - (minus) – wykluczanie kryteriów (np. -movie).
  • ( ) – grupowanie wielu wyszukiwanych haseł (np. subject:(dinner film)).

Przykłady:

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

Pole zbiorcze _include_trash.

Pole _include_trash może mieć tylko jedną z tych wartości:
includeTrash

boolean

Opcjonalnie. Uwzględnij w wynikach wątki z folderu KOSZ. Wartość domyślna to fałsz.

Pole zbiorcze _view.

Pole _view może mieć tylko jedną z tych wartości:
view

enum (ThreadView)

Opcjonalnie. Określa pola wypełniane w przypadku wątków na liście wątków. Domyślna wartość to THREAD_VIEW_MINIMAL. THREAD_VIEW_MINIMAL zwraca id, snippet, subject, from, to, cc, date, labelIds. THREAD_VIEW_METADATA_ONLY zwraca id, from, to, cc, date, labelIds.

ThreadView

Wyliczenie określające pola wypełniane w przypadku wątków w odpowiedziach ListThreads i SearchThreads.

Wartości w polu enum
THREAD_VIEW_UNSPECIFIED W celu zapewnienia zgodności wstecznej jest mapowane na THREAD_VIEW_MINIMAL.
THREAD_VIEW_METADATA_ONLY Zwraca identyfikator, od, do, cc, datę i identyfikatory etykiet.
THREAD_VIEW_MINIMAL Zwraca identyfikator, fragment, temat, od, do, cc, datę i identyfikatory etykiet.

Schemat wyjściowy

Wiadomość z odpowiedzią na RPC SearchThreads.

SearchThreadsResponse

Zapis JSON 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": string,
  "resultCountEstimate": string
}
Pola
threads[]

object (Thread)

Lista podsumowań wątków.
nextPageToken

string

Token, którego można użyć w kolejnym wywołaniu, aby pobrać następną stronę wątków. Wyświetlany tylko wtedy, gdy jest więcej wyników. Jeśli liczba wątków pasujących do zapytania przekracza limit page_size, odpowiedź będzie zawierać next_page_token. Aby pobrać następną stronę wyników, przekaż ten token w polu page_token następnego żądania SearchThreadsRequest.
resultCountEstimate

string (int64 format)

Szacunkowa liczba wyników tego zapytania. Należy ją traktować jako dolną granicę, więc jeśli np. wynosi 500, użytkownikowi można podać liczbę „500+”.

Wątek

Zapis JSON 
{
  "id": string,
  "messages": [
    {
      object (Message)
    }
  ]
}
Pola
id

string

Unikalny identyfikator wątku.
messages[]

object (Message)

Lista wiadomości w wątku, uporządkowana chronologicznie.

Wiadomość

Zapis 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
  ]
}
Pola
id

string

Unikalny identyfikator wiadomości.
snippet

string

Fragment treści wiadomości.
subject

string

Temat wiadomości wyodrębniony z nagłówków:
sender

string

Adres e-mail nadawcy.
toRecipients[]

string

Adresy e-mail odbiorców.
ccRecipients[]

string

Adresy e-mail odbiorców w polu DW.
date

string

Data wiadomości w formacie ISO 8601 (RRRR-MM-DD).
plaintextBody

string

Pełna treść, wypełniana tylko wtedy, gdy MessageFormat ma wartość FULL_CONTENT.
attachmentIds[]

string

Tylko dane wyjściowe. Identyfikatory załączników, wypełniane tylko wtedy, gdy MessageFormat ma wartość FULL_CONTENT.
htmlBody

string

Zawartość HTML e-maila. Wypełniana tylko wtedy, gdy MessageFormat ma wartość FULL_CONTENT.
attachments[]

object (AttachmentMetadata)

Tylko dane wyjściowe. Załączniki, wypełniane tylko wtedy, gdy MessageFormat ma wartość FULL_CONTENT.
labelIds[]

string

Identyfikatory etykiet dołączonych do wiadomości. Zawiera identyfikatory etykiet użytkownika i standardowych etykiet systemowych, które są ograniczone do INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, SENT, DRAFT, CHAT.

AttachmentMetadata

Zapis JSON 
{
  "id": string,
  "mimeType": string,
  "filename": string
}
Pola
id

string

Tylko dane wyjściowe. Identyfikator załącznika.
mimeType

string

Typ MIME załącznika.
filename

string

Nazwa pliku załącznika.

Adnotacje narzędzi

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌

Zakresy autoryzacji

Wymaga jednego z tych zakresów OAuth:

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