MCP Tools Reference: gmailmcp.googleapis.com

Araç: search_threads

Kimliği doğrulanmış kullanıcının Gmail hesabındaki e-posta yazışmalarını listeler.

Bu araç, ileti dizilerini bir sorgu dizesine göre filtreleyebilir ve sayfalara ayırmayı destekler. Kimlikleri ve ilgili iletileri de içeren bir ileti dizisi listesi döndürür. İlgili her iletide, e-posta mesajının snippet'i, konu, gönderen, alıcılar vb. gibi ayrıntılar yer alır. view parametresi, ilgili iletilerde hangi alanların doldurulacağını kontrol eder. Varsayılan olarak (veya THREAD_VIEW_MINIMAL ile) konu ve snippet'i içerir. Konuyu ve snippet'i hariç tutmak için THREAD_VIEW_METADATA_ONLY simgesini kullanın. Bu araç tarafından tam e-posta mesajlarının döndürülmediğini unutmayın. Gerekirse tam e-posta mesajını getirmek için "get_thread" aracını bir ileti dizisi kimliğiyle kullanın. Hariç tutulan ölçütlere sahip ileti dizileri sonuçlarda görünmeye devam edebilir. Bunun nedeni, Gmail'in önce eşleşen iletileri tanımlamasıdır. Örneğin, -is:starred ifadesini aradığınızda Gmail, aynı ileti dizisindeki diğer e-postalar yıldızlı olsa bile yıldızsız en az bir ileti içeriyorsa ileti dizisinin tamamını bulur.

Aşağıdaki örnekte, search_threads MCP aracını çağırmak için curl simgesinin nasıl kullanılacağı gösterilmektedir.

Curl İsteği 
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
}'

Giriş Şeması

SearchThreads RPC için istek mesajı.

SearchThreadsRequest

JSON gösterimi 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean

  "view": enum (ThreadView)
}
Alanlar

_page_size birleşik alanı.

_page_size aşağıdakilerden yalnızca biri olabilir:
pageSize

integer

İsteğe bağlı. Döndürülecek maksimum ileti dizisi sayısı. Belirtilmemişse varsayılan olarak 20 olur. İzin verilen en yüksek değer 50'dir.

_page_token birleşik alanı.

_page_token aşağıdakilerden yalnızca biri olabilir:
pageToken

string

İsteğe bağlı. Listedeki belirli bir sonuç sayfasını almak için kullanılan sayfa jetonu. İlk sayfayı getirmek için boş bırakın. Bu parametre, özellikle sorguyla eşleşen iş parçacığı sayısı page_size sınırını aştığında, önceki SearchThreads çağrısının kaldığı yerden sonuç getirmeye devam etmek için öncelikle sayfalara ayırma işleminde kullanılır.

_query birleşik alanı.

_query aşağıdakilerden yalnızca biri olabilir:
query

string

İsteğe bağlı. İş parçacıklarını filtrelemek için kullanılan sorgu dizesi. Bu aracı kullanmak için doğal dil sorgularının önceden Gmail söz dizimi sorgularına dönüştürülmesi gerekir. Atlanırsa tüm ileti dizileri (varsayılan olarak spam ve çöp kutusu hariç) listelenir.

Kategoriye Göre Desteklenen Operatörler:

Gönderen ve alıcı:

  • from:<email>: Belirli bir kişiden gönderilenler.
  • to:<email>: Belirli bir kişiye gönderilenler.
  • cc:<email>: Cc alanındaki belirli kişiler.
  • bcc:<email>: Bcc alanındaki belirli kişiler.
  • deliveredto:<email>: Belirli bir adrese teslim edildi.
  • list:<email>: Belirli bir posta listesinden gelen iletiler.

Saat ve Tarih:

  • after:YYYY/MM/DD / newer:YYYY/MM/DD: Belirli bir tarihten sonra alınanlar.
  • before:YYYY/MM/DD / older:YYYY/MM/DD: Belirli bir tarihten önce alınmış.
  • older_than:<duration>: Belirli bir süreden daha eski (örneğin, 1y, 2d).
  • newer_than:<duration>: Belirli bir süreden daha yeni.

İçerik:

  • subject:<words> — Konu satırındaki kelimeler.
  • has:<type>: Belirli içerik türlerine (ek, Drive, YouTube, doküman) sahip.
  • filename:<name>: Belirli bir ad veya türde ek.
  • "<word/phrase>": Bir kelimeyi veya kelime öbeğini eksiksiz olarak arama (örneğin, "holiday", "holiday vacation").
  • +<word>: Bir kelimeyle tam olarak eşleşir. (örneğin, +holiday, +unicorn)
  • rfc822msgid:<id>: Belirli ileti kimliği üstbilgisi.
  • AROUND <distance> — Birbirine yakın kelimeleri bulur (örneğin, holiday AROUND 10 vacation).

Etiketler ve Kategoriler:

  • label:<name> — Belirli bir etiket altında. Bu araç, görünen adları değil, plak şirketi kimliklerini kabul eder. Kimliği almak için list_labels aracını kullanın.
  • category:<name> — Bir kategoride (birincil, sosyal, tanıtımlar, güncellemeler, forumlar, rezervasyonlar, satın alma işlemleri).
  • in:<label>: Belirli etiketlerde (arşiv, ertelenmiş, çöp kutusu, gönderilmiş, gelen kutusu) arama yapın. Örneğin, in:trash, in:inbox. Arşivlenen ve gönderilen iletiler varsayılan olarak dahil edilir. Bunları hariç tutmak için -in:archive ve -in:sent simgelerini kullanın. Taslaklar, araç tarafından varsayılan olarak açıkça hariç tutulur. Aramayı yalnızca gelen kutusuyla sınırlamak için in:inbox simgesini kullanın.
  • has:userlabels: Kullanıcı etiketleri içerir.
  • has:nouserlabels: Kullanıcı etiketi yok.
  • has:*-star — Belirli yıldız renkleri (etkinleştirilmişse, örneğin has:yellow-star).
  • in:draft: Taslaklarda arama yapın. -in:draft, taslakların arama sonuçlarından hariç tutulması anlamına gelir.
  • in:sent: Gönderilmiş iletilerde arama yapın.
  • in:anywhere: Spam ve çöp kutusu dahil olmak üzere tüm klasörlerde arama yapın.

Durum:

  • is:<status>: Duruma göre arama yapın (önemli, yıldızlı, okunmamış, okunmuş, sessize alınmış).

Boyut:

  • size:<bytes>: Bayt cinsinden belirli boyut.
  • larger:<size> / smaller:<size>: Bir boyuttan büyük veya küçük (örneğin, 10M 10 MB için).

Mantık ve Gruplandırma:

  • AND: Tüm ölçütlerle eşleşir (varsayılan davranış).
  • OR veya { }: Bir veya daha fazla ölçütle (örneğin, from:amy OR from:david, {from:amy from:david}) eşleşir.
  • - (eksi): Ölçütleri hariç tutmak için kullanılır (örneğin, -movie).
  • ( ): Birden çok arama terimini gruplandırır (örneğin, subject:(dinner film)).

Örnekler:

  • 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 birleşik alanı.

_include_trash aşağıdakilerden yalnızca biri olabilir:
includeTrash

boolean

İsteğe bağlı. ÇÖP KUTUSU'ndaki ileti dizilerini sonuçlara dahil etme Varsayılan olarak false değerine ayarlanır.

_view birleşik alanı.

_view aşağıdakilerden yalnızca biri olabilir:
view

enum (ThreadView)

İsteğe bağlı. İleti dizisi listesindeki ileti dizileri için doldurulan alanları kontrol eder. Varsayılan olarak THREAD_VIEW_MINIMAL değerine ayarlanır. THREAD_VIEW_MINIMAL; id, snippet, subject, from, to, cc, date, labelIds değerlerini döndürür. THREAD_VIEW_METADATA_ONLY, id, from, to, cc, date, labelIds değerlerini döndürür.

ThreadView

ListThreads ve SearchThreads yanıtında ileti dizileri için doldurulan alanları kontrol eden enum.

Sıralamalar
THREAD_VIEW_UNSPECIFIED Geriye dönük uyumluluk için THREAD_VIEW_MINIMAL ile eşlenir.
THREAD_VIEW_METADATA_ONLY id, from, to, cc, date, labelIds değerlerini döndürür.
THREAD_VIEW_MINIMAL Kimlik, snippet, konu, gönderen, alıcı, cc, tarih, etiket kimlikleri değerlerini döndürür.

Çıkış Şeması

SearchThreads RPC'si için yanıt mesajı.

SearchThreadsResponse

JSON gösterimi 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": string,
  "resultCountEstimate": string
}
Alanlar
threads[]

object (Thread)

Mesaj dizisi özetlerinin listesi.
nextPageToken

string

Bir sonraki görüşmede ileti dizilerinin sonraki sayfasını almak için kullanılabilecek bir jeton. Yalnızca daha fazla sonuç varsa gösterilir. Sorguyla eşleşen ileti dizilerinin sayısı page_size sınırını aşarsa yanıtta next_page_token yer alır. Sonraki sonuç sayfasını almak için bu jetonu sonraki SearchThreadsRequest öğesinin page_token alanına iletin.
resultCountEstimate

string (int64 format)

Bu sorgu için tahmini sonuç sayısı. Alt sınır olarak değerlendirilmelidir. Örneğin, 500 ise sayı kullanıcıya "500+" olarak bildirilebilir.

İplik

JSON gösterimi 
{
  "id": string,
  "messages": [
    {
      object (Message)
    }
  ]
}
Alanlar
id

string

İş parçacığının benzersiz tanımlayıcısı.
messages[]

object (Message)

İleti dizisindeki mesajların kronolojik olarak sıralanmış listesi.

Mesaj

JSON gösterimi 
{
  "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
  ]
}
Alanlar
id

string

Mesajın benzersiz tanımlayıcısı.
snippet

string

E-posta mesajının snippet'i.
subject

string

Üstbilgilerden çıkarılan ileti konusu:
sender

string

Gönderenin e-posta adresi.
toRecipients[]

string

Alıcı e-posta adresleri
ccRecipients[]

string

CC alıcılarının e-posta adresleri.
date

string

İletinin ISO 8601 biçimindeki tarihi (YYYY-AA-GG).
plaintextBody

string

İletinin tam içeriği. Yalnızca MessageFormat FULL_CONTENT ise doldurulur.
attachmentIds[]

string

Yalnızca çıkış. Ek kimlikleri, yalnızca MessageFormat FULL_CONTENT ise doldurulur.
htmlBody

string

E-postanın HTML içeriği. Yalnızca MessageFormat FULL_CONTENT ise doldurulur.
attachments[]

object (AttachmentMetadata)

Yalnızca çıkış. Ekler, yalnızca MessageFormat FULL_CONTENT ise doldurulur.
labelIds[]

string

İletiye eklenen etiketlerin kimlikleri. INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, SENT, DRAFT, CHAT ile sınırlı kullanıcı etiketlerinin ve standart sistem etiketlerinin kimliklerini içerir.

AttachmentMetadata

JSON gösterimi 
{
  "id": string,
  "mimeType": string,
  "filename": string
}
Alanlar
id

string

Yalnızca çıkış. Ekin kimliği.
mimeType

string

Ekin MIME türü.
filename

string

Ekin dosya adı.

Araç Ek Açıklamaları

Yıkıcı İpucu: ❌ | İdempotent İpucu: ✅ | Salt Okunur İpucu: ✅ | Açık Dünya İpucu: ❌

Yetkilendirme Kapsamları

Aşağıdaki OAuth kapsamlarından birini gerektirir:

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