MCP Tools Reference: gmailmcp.googleapis.com

Alat: search_threads

Mencantumkan rangkaian email dari akun Gmail pengguna terautentikasi.

Alat ini dapat memfilter rangkaian pesan berdasarkan string kueri dan mendukung penomoran halaman. Tindakan ini akan menampilkan daftar rangkaian pesan, termasuk ID dan pesan terkaitnya. Setiap pesan terkait berisi detail seperti cuplikan isi pesan, subjek, pengirim, penerima, dll. Parameter view mengontrol kolom mana yang diisi dalam pesan terkait. Secara default (atau dengan THREAD_VIEW_MINIMAL), ini mencakup subjek dan cuplikan. Gunakan THREAD_VIEW_METADATA_ONLY untuk mengecualikan subjek dan cuplikan. Perhatikan bahwa isi pesan lengkap tidak ditampilkan oleh alat ini; gunakan alat 'get_thread' dengan ID rangkaian pesan untuk mengambil isi pesan lengkap jika diperlukan. Thread dengan kriteria yang dikecualikan mungkin masih muncul di hasil. Hal ini terjadi karena Gmail mengidentifikasi pesan yang cocok terlebih dahulu. Misalnya, jika Anda menelusuri -is:starred, Gmail akan menemukan seluruh rangkaian pesan jika rangkaian pesan tersebut berisi setidaknya satu pesan yang tidak berbintang, meskipun email lain dalam percakapan yang sama berbintang.

Contoh berikut menunjukkan cara menggunakan curl untuk memanggil alat MCP search_threads.

Permintaan 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
}'

Skema Input

Pesan permintaan untuk RPC SearchThreads.

SearchThreadsRequest

Representasi JSON 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean

  "view": enum (ThreadView)
}
Kolom

Kolom union _page_size.

_page_size hanya dapat berupa salah satu dari hal berikut:
pageSize

integer

Opsional. Jumlah maksimum rangkaian pesan yang akan ditampilkan. Jika tidak ditentukan, nilai defaultnya adalah 20. Nilai maksimum yang diizinkan adalah 50.

Kolom union _page_token.

_page_token hanya dapat berupa salah satu dari hal berikut:
pageToken

string

Opsional. Token halaman untuk mengambil halaman hasil tertentu dalam daftar. Biarkan kosong untuk mengambil halaman pertama. Parameter ini terutama digunakan untuk penomoran halaman guna melanjutkan pengambilan hasil dari tempat panggilan SearchThreads sebelumnya berhenti, terutama saat jumlah thread yang cocok dengan kueri melebihi batas page_size.

Kolom union _query.

_query hanya dapat berupa salah satu dari hal berikut:
query

string

Opsional. String kueri untuk memfilter rangkaian pesan. Kueri bahasa alami harus dikonversi terlebih dahulu menjadi kueri sintaksis Gmail untuk menggunakan alat ini. Jika tidak disertakan, semua rangkaian pesan (kecuali spam dan sampah secara default) akan dicantumkan.

Operator yang Didukung menurut Kategori:

Pengirim & Penerima:

  • from:<email> — Dikirim dari orang tertentu.
  • to:<email> — Dikirim ke orang tertentu.
  • cc:<email> — Orang tertentu di Cc.
  • bcc:<email> — Orang tertentu di Bcc.
  • deliveredto:<email> — Dikirim ke alamat tertentu.
  • list:<email> — Dari milis tertentu.

Waktu & Tanggal:

  • after:YYYY/MM/DD / newer:YYYY/MM/DD — Diterima setelah tanggal tertentu.
  • before:YYYY/MM/DD / older:YYYY/MM/DD — Diterima sebelum tanggal.
  • older_than:<duration> — Lebih lama dari durasi (misalnya, 1y, 2d).
  • newer_than:<duration> — Lebih baru dari durasi.

Konten:

  • subject:<words> — Kata-kata dalam baris subjek.
  • has:<type> — Memiliki jenis konten tertentu (lampiran, drive, youtube, dokumen).
  • filename:<name> — Lampiran dengan nama atau jenis tertentu.
  • "<word/phrase>" — Menelusuri kata atau frasa yang sama persis. (misalnya, "holiday", "holiday vacation").
  • +<word> — Mencocokkan kata dengan tepat. (misalnya, +holiday, +unicorn)
  • rfc822msgid:<id> — Header ID pesan tertentu.
  • AROUND <distance> — Menemukan kata-kata yang saling berdekatan (misalnya, holiday AROUND 10 vacation).

Label & Kategori:

  • label:<name> — Dalam label tertentu. Alat ini menerima ID label, bukan nama tampilan. Gunakan alat list_labels untuk mendapatkan ID.
  • category:<name> — Dalam kategori (utama, sosial, promosi, info terbaru, forum, reservasi, pembelian).
  • in:<label> — Menelusuri di label tertentu (arsip, ditunda, sampah, terkirim, kotak masuk). Misalnya, in:trash, in:inbox. Pesan yang diarsipkan dan dikirim disertakan secara default; gunakan -in:archive dan -in:sent untuk mengecualikannya. Draf secara eksplisit dikecualikan secara default oleh alat ini. Gunakan in:inbox untuk membatasi penelusuran hanya ke kotak masuk.
  • has:userlabels — Memiliki label pengguna.
  • has:nouserlabels — Tidak memiliki label pengguna.
  • has:*-star — Warna bintang tertentu (jika diaktifkan, misalnya, has:yellow-star).
  • in:draft — Menelusuri di draf. -in:draft berarti mengecualikan draf dari hasil penelusuran.
  • in:sent — Menelusuri pesan terkirim.
  • in:anywhere — Menelusuri di semua folder (termasuk spam dan sampah).

Status:

  • is:<status> — Menelusuri berdasarkan status (penting, berbintang, belum dibaca, telah dibaca, disenyapkan).

Ukuran:

  • size:<bytes> — Ukuran tertentu dalam byte.
  • larger:<size> / smaller:<size> — Lebih besar atau lebih kecil dari ukuran (misalnya, 10M untuk 10 MB).

Logika & Pengelompokan:

  • AND — Cocokkan semua kriteria (perilaku default).
  • OR atau { } — Mencocokkan satu atau beberapa kriteria (misalnya, from:amy OR from:david, {from:amy from:david}).
  • - (minus) — Mengecualikan kriteria (misalnya, -movie).
  • ( ) — Mengelompokkan beberapa istilah penelusuran (misalnya, subject:(dinner film)).

Contoh:

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

Kolom union _include_trash.

_include_trash hanya dapat berupa salah satu dari hal berikut:
includeTrash

boolean

Opsional. Sertakan rangkaian pesan dari SAMPAH dalam hasil. Nilai defaultnya adalah false (salah).

Kolom union _view.

_view hanya dapat berupa salah satu dari hal berikut:
view

enum (ThreadView)

Opsional. Mengontrol kolom yang diisi untuk rangkaian pesan dalam daftar rangkaian pesan. Default-nya adalah THREAD_VIEW_MINIMAL. THREAD_VIEW_MINIMAL menampilkan id, cuplikan, subjek, dari, ke, cc, tanggal, labelIds. THREAD_VIEW_METADATA_ONLY menampilkan id, from, to, cc, date, labelIds.

ThreadView

Enum untuk mengontrol kolom yang diisi untuk rangkaian pesan dalam respons ListThreads dan SearchThreads.

Enum
THREAD_VIEW_UNSPECIFIED Dipetakan ke THREAD_VIEW_MINIMAL untuk kompatibilitas mundur.
THREAD_VIEW_METADATA_ONLY Menampilkan id, from, to, cc, date, labelIds.
THREAD_VIEW_MINIMAL Menampilkan id, cuplikan, subjek, dari, ke, cc, tanggal, labelIds.

Skema Output

Pesan respons untuk RPC SearchThreads.

SearchThreadsResponse

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

object (Thread)

Daftar ringkasan rangkaian pesan.
nextPageToken

string

Token yang dapat digunakan dalam panggilan berikutnya untuk mengambil halaman berikutnya dari rangkaian pesan. Hanya ada jika ada hasil lainnya. Jika jumlah rangkaian pesan yang cocok dengan kueri melebihi batas page_size, respons akan berisi next_page_token. Untuk mengambil halaman hasil berikutnya, teruskan token ini di kolom page_token dari SearchThreadsRequest berikutnya.
resultCountEstimate

string (int64 format)

Perkiraan jumlah hasil untuk kueri ini. Nilai ini harus diperlakukan sebagai batas bawah, jadi misalnya jika nilainya 500, jumlah tersebut dapat dilaporkan kepada pengguna sebagai "500+".

Rangkaian pesan

Representasi JSON 
{
  "id": string,
  "messages": [
    {
      object (Message)
    }
  ]
}
Kolom
id

string

ID unik rangkaian pesan.
messages[]

object (Message)

Daftar pesan dalam rangkaian pesan, diurutkan secara kronologis.

Pesan

Representasi 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
  ]
}
Kolom
id

string

ID unik pesan.
snippet

string

Cuplikan isi pesan.
subject

string

Subjek pesan yang diekstrak dari header:
sender

string

Alamat email pengirim.
toRecipients[]

string

Ke alamat email penerima.
ccRecipients[]

string

Alamat email penerima CC.
date

string

Tanggal pesan dalam format ISO 8601 (YYYY-MM-DD).
plaintextBody

string

Konten isi pesan lengkap, hanya diisi jika MessageFormat adalah FULL_CONTENT.
attachmentIds[]

string

Hanya output. ID lampiran, hanya diisi jika MessageFormat adalah FULL_CONTENT.
htmlBody

string

Konten HTML email, hanya diisi jika MessageFormat adalah FULL_CONTENT.
attachments[]

object (AttachmentMetadata)

Hanya output. Lampiran, hanya diisi jika MessageFormat adalah FULL_CONTENT.
labelIds[]

string

ID label yang dilampirkan ke pesan. Mencakup ID label pengguna dan label sistem standar yang dibatasi hingga INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, SENT, DRAFT, CHAT.

AttachmentMetadata

Representasi JSON 
{
  "id": string,
  "mimeType": string,
  "filename": string
}
Kolom
id

string

Hanya output. ID lampiran.
mimeType

string

Jenis MIME lampiran.
filename

string

Nama file lampiran.

Anotasi Alat

Petunjuk Destruktif: ❌ | Petunjuk Idempoten: ✅ | Petunjuk Hanya Baca: ✅ | Petunjuk Dunia Terbuka: ❌

Cakupan Otorisasi

Memerlukan salah satu cakupan OAuth berikut:

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