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 MCP.

طلب 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
}'

مخطط الإدخال

رسالة الطلب لاستدعاء إجراء SearchThreads عن بُعد

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

اختياريّ. تضمين سلاسل محادثات من مجلد المهملات في النتائج القيمة التلقائية هي "خطأ".

حقل الربط _view

يمكن أن يكون التعليق _view إحدى القيم التالية فقط:
view

enum (ThreadView)

اختياريّ. تتحكّم هذه السمة في الحقول التي تتم تعبئتها لسلاسل المحادثات في قائمة سلاسل المحادثات. القيمة التلقائية هي THREAD_VIEW_MINIMAL. تعرض الدالة THREAD_VIEW_MINIMAL المعرّف والمقتطف والموضوع والمرسل والمستلم ونسخة إلى والتاريخ ومعرّفات التصنيفات. تعرض THREAD_VIEW_METADATA_ONLY المعرّف و"من" و"إلى" و"نسخة إلى" والتاريخ وlabelIds فقط.

ThreadView

تعداد للتحكّم في الحقول التي يتم ملؤها لسلاسل المحادثات في ردَّي ListThreads وSearchThreads.

عمليات التعداد
THREAD_VIEW_UNSPECIFIED يتم ربطها بـ THREAD_VIEW_MINIMAL للتوافق مع الأنظمة القديمة.
THREAD_VIEW_METADATA_ONLY تعرض هذه الطريقة المعرّف id، وfrom، وto، وcc، وdate، وlabelIds.
THREAD_VIEW_MINIMAL تعرض هذه الطريقة رقم التعريف والمقتطف والموضوع والمُرسِل والمستلِم والنسخة إلى والتاريخ وأرقام تعريف التصنيفات.

مخطط النتائج

رسالة الردّ على استدعاء إجراء SearchThreads عن بُعد.

SearchThreadsResponse

تمثيل JSON 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": string,
  "resultCountEstimate": string
}
الحقول
threads[]

object (Thread)

قائمة بملخّصات سلاسل المحادثات
nextPageToken

string

رمز مميّز يمكن استخدامه في طلب لاحق لاسترداد الصفحة التالية من سلاسل المحادثات. يجب عرضها فقط إذا كانت هناك نتائج إضافية. إذا كان عدد سلاسل المحادثات المطابقة لطلب البحث يتجاوز الحدّ الأقصى المسموح به في page_size، سيتضمّن الردّ next_page_token. لاسترداد الصفحة التالية من النتائج، مرِّر هذا الرمز المميّز في الحقل page_token من SearchThreadsRequest التالي.
resultCountEstimate

string (int64 format)

تمثّل هذه السمة عدد النتائج المقدَّر لطلب البحث هذا. يجب التعامل معها كحدّ أدنى، لذا إذا كانت 500 مثلاً، يمكن إبلاغ المستخدم بالعدد على أنّه "500 أو أكثر".

Thread

تمثيل 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

تاريخ الرسالة بتنسيق ISO 8601 (YYYY-MM-DD)
plaintextBody

string

محتوى النص الكامل، ويتم ملؤه فقط إذا كانت قيمة MessageFormat هي FULL_CONTENT.
attachmentIds[]

string

النتائج فقط. معرّفات المرفقات، ويتم ملؤها فقط إذا كانت قيمة MessageFormat هي FULL_CONTENT.
htmlBody

string

محتوى HTML للرسالة الإلكترونية، تتم تعبئته فقط إذا كانت قيمة 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

نوع MIME للمرفق.
filename

string

اسم ملف المرفق

التعليقات التوضيحية للأدوات

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

نطاقات التفويض

يجب توفير أحد نطاقات OAuth التالية:

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