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. Pamiętaj, że to narzędzie nie zwraca pełnej treści wiadomości. Jeśli jest to potrzebne, użyj narzędzia „get_thread” z identyfikatorem wątku, aby pobrać pełną treść wiadomości. 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ą znaku curl wywołać narzędzie search_threads MCP.

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

Schemat danych wejściowych

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

SearchThreadsRequest

Zapis JSON 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean
}
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ą zostać 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: od: – wysłane przez konkretną osobę. do: – wysłane do konkretnej osoby. DW: – określone osoby w polu DW. bcc: – konkretne osoby w polu UDW. deliveredto: – dostarczono na określony adres. list: – z określonej listy adresowej.

Czas i data: after:RRRR/MM/DD / newer:RRRR/MM/DD – otrzymane po dacie. before:RRRR/MM/DD / older:RRRR/MM/DD – otrzymane przed datą. older_than: – starsze niż określony czas (np. 1 rok, 2 dni). newer_than: - Nowsze niż określony czas.

Treść: temat: – słowa w temacie. has: – zawiera określone typy treści (załącznik, Dysk, YouTube, dokument). filename: – załącznik o określonej nazwie lub typie. „<słowo/wyrażenie>” – wyszukaj dokładne słowo lub wyrażenie. (np. „wakacje”, „urlop”). + – dopasowanie ścisłe słowa. (np. +wakacje, +jednorożec) rfc822msgid: – konkretny nagłówek identyfikatora wiadomości. AROUND – wyszukiwanie słów blisko siebie (np. święta AROUND 10 wakacje).

Etykiety i kategorie: label: – w ramach określonej etykiety. Narzędzie akceptuje identyfikatory etykiet, a nie wyświetlane nazwy. Aby uzyskać identyfikator, użyj narzędzia list_labels. category: – w kategorii (główne, społeczności, oferty, powiadomienia, fora, rezerwacje, zakupy); in:

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

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

Logika i grupowanie: ORAZ – dopasuj wszystkie kryteria (domyślne działanie). OR lub { } – dopasowanie co najmniej 1 kryterium (np. from:amy OR from:david, {from:amy from:david}). – (minus) – wyklucz kryteria (np. -film). ( ) – 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 wersje robocze z KOSZA. Wartość domyślna to fałsz.

Schemat wyjściowy

Wiadomość z odpowiedzią dla RPC SearchThreads.

SearchThreadsResponse

Zapis JSON 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": 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.

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
  ]
}
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.

Adnotacje narzędzi

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