MCP Tools Reference: gmailmcp.googleapis.com

टूल: search_threads

इस तरीके से, पुष्टि किए गए उपयोगकर्ता के Gmail खाते से ईमेल थ्रेड की सूची मिलती है.

यह टूल, क्वेरी स्ट्रिंग के आधार पर थ्रेड को फ़िल्टर कर सकता है. साथ ही, इसमें पेज नंबर के हिसाब से नतीजे दिखाने की सुविधा भी काम करती है. यह थ्रेड की सूची दिखाता है. इसमें उनके आईडी और उनसे जुड़े मैसेज शामिल होते हैं. मिलते-जुलते हर मैसेज में, मैसेज का मुख्य हिस्सा का स्निपेट, विषय, भेजने वाला, पाने वाले वगैरह की जानकारी होती है. view पैरामीटर से यह कंट्रोल किया जाता है कि मिलते-जुलते मैसेज में कौनसे फ़ील्ड भरे जाएं. डिफ़ॉल्ट रूप से (या THREAD_VIEW_MINIMAL के साथ), इसमें विषय और स्निपेट शामिल होता है. विषय और स्निपेट को बाहर रखने के लिए, THREAD_VIEW_METADATA_ONLY का इस्तेमाल करें. ध्यान दें कि यह टूल, पूरे मैसेज का कॉन्टेंट नहीं दिखाता है. अगर आपको पूरे मैसेज का कॉन्टेंट चाहिए, तो थ्रेड आईडी के साथ 'get_thread' टूल का इस्तेमाल करें. ऐसा हो सकता है कि बाहर रखी गई शर्तों वाली थ्रेड अब भी नतीजों में दिखें. ऐसा इसलिए होता है, क्योंकि Gmail सबसे पहले मिलते-जुलते ईमेल की पहचान करता है. उदाहरण के लिए, अगर आपने -is:starred खोजा है, तो Gmail पूरी थ्रेड को ढूंढ सकता है. भले ही, उस थ्रेड में शामिल अन्य ईमेल पर स्टार का निशान लगा हो. हालांकि, इसके लिए ज़रूरी है कि उस थ्रेड में कम से कम एक ईमेल ऐसा हो जिस पर स्टार का निशान न लगा हो.

यहां दिए गए सैंपल में, curl का इस्तेमाल करके search_threads एमसीपी टूल को चालू करने का तरीका बताया गया है.

कर्ल अनुरोध 
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
}'

इनपुट स्कीमा

SearchThreads RPC के लिए अनुरोध मैसेज.

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> — कॉपी फ़ील्ड में शामिल किए गए चुनिंदा लोग.
  • 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> — इसमें कुछ खास तरह का कॉन्टेंट होता है. जैसे, अटैचमेंट, Drive, 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 एमबी के लिए).

लॉजिक और ग्रुपिंग:

  • 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

ज़रूरी नहीं. नतीजों में, TRASH फ़ोल्डर में मौजूद थ्रेड शामिल करें. डिफ़ॉल्ट रूप से, यह 'गलत' पर सेट होती है.

यूनियन फ़ील्ड _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

यह एक इनम है. इसका इस्तेमाल, ListThreads और SearchThreads के जवाब में थ्रेड के लिए भरे गए फ़ील्ड को कंट्रोल करने के लिए किया जाता है.

Enums
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 दिखाता है.

आउटपुट स्कीमा

SearchThreads RPC के लिए जवाब का मैसेज.

SearchThreadsResponse

JSON के काेड में दिखाना 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": string,
  "resultCountEstimate": string
}
फ़ील्ड
threads[]

object (Thread)

थ्रेड के सारांश की सूची.
nextPageToken

string

यह एक ऐसा टोकन है जिसका इस्तेमाल बाद में किए जाने वाले कॉल में किया जा सकता है. इससे थ्रेड का अगला पेज वापस पाया जा सकता है. यह तब ही दिखता है, जब ज़्यादा नतीजे मौजूद हों. अगर क्वेरी से मेल खाने वाली थ्रेड की संख्या, page_size की सीमा से ज़्यादा है, तो जवाब में next_page_token शामिल होगा. नतीजों का अगला पेज पाने के लिए, इस टोकन को अगले SearchThreadsRequest के page_token फ़ील्ड में पास करें.
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

आईएसओ 8601 फ़ॉर्मैट (YYYY-MM-DD) में मैसेज की तारीख.
plaintextBody

string

मैसेज का पूरा कॉन्टेंट. यह सिर्फ़ तब दिखता है, जब MessageFormat FULL_CONTENT पर सेट हो.
attachmentIds[]

string

सिर्फ़ आउटपुट के लिए. अटैचमेंट आईडी. ये आईडी सिर्फ़ तब दिखते हैं, जब MessageFormat FULL_CONTENT पर सेट हो.
htmlBody

string

ईमेल का एचटीएमएल कॉन्टेंट. यह सिर्फ़ तब दिखता है, जब MessageFormat को FULL_CONTENT पर सेट किया गया हो.
attachments[]

object (AttachmentMetadata)

सिर्फ़ आउटपुट के लिए. अटैचमेंट. यह जानकारी सिर्फ़ तब अपने-आप भरती है, जब MessageFormat FULL_CONTENT पर सेट हो.
labelIds[]

string

मैसेज से जुड़े लेबल के आईडी. इसमें उपयोगकर्ता के लेबल और स्टैंडर्ड सिस्टम लेबल के आईडी शामिल होते हैं. ये आईडी सिर्फ़ INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, SENT, DRAFT, CHAT तक सीमित होते हैं.

AttachmentMetadata

JSON के काेड में दिखाना 
{
  "id": string,
  "mimeType": string,
  "filename": string
}
फ़ील्ड
id

string

सिर्फ़ आउटपुट के लिए. अटैचमेंट का आईडी.
mimeType

string

अटैचमेंट का एमआईएमई टाइप.
filename

string

अटैचमेंट की फ़ाइल का नाम.

टूल एनोटेशन

बदलाव करने वाला हिंट: ❌ | एक ही बार लागू होने वाला हिंट: ✅ | सिर्फ़ पढ़ने वाला हिंट: ✅ | ओपन वर्ल्ड हिंट: ❌

अनुमति पाने के लिंक

इसके लिए, इनमें से किसी एक OAuth स्कोप की ज़रूरत होती है:

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