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

طرحواره ورودی

درخواست پیام برای RPC مربوط به SearchThreads.

جستجوموضوعاتدرخواست

نمایش 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

اختیاری. یک رشته پرس‌وجو برای فیلتر کردن رشته‌ها. برای استفاده از این ابزار، پرس‌وجوهای زبان طبیعی باید از قبل به پرس‌وجوهای نحوی جیمیل تبدیل شوند. در صورت حذف، همه رشته‌ها (به استثنای هرزنامه و زباله به طور پیش‌فرض) فهرست می‌شوند.

اپراتورهای پشتیبانی شده بر اساس دسته بندی:

فرستنده و گیرنده:

  • from:<email> — ارسال شده از یک شخص خاص.
  • to:<email> — برای یک شخص خاص ارسال می‌شود.
  • cc:<email> — افراد خاص در Cc.
  • bcc:<email> — افراد خاص در رونوشت از ایمیل (bcc).
  • 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> — انواع محتوای خاصی (پیوست، درایو، یوتیوب، سند) دارد.
  • 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

اختیاری. رشته‌های موجود در سطل زباله را در نتایج لحاظ کنید. پیش‌فرض روی false است.

_view میدان اتحادیه.

_view فقط می‌تواند یکی از موارد زیر باشد:

view

enum ( ThreadView )

اختیاری. فیلدهای پر شده برای رشته‌ها در لیست رشته‌ها را کنترل می‌کند. مقدار پیش‌فرض THREAD_VIEW_MINIMAL است. THREAD_VIEW_MINIMAL شناسه، قطعه کد، موضوع، از، به، cc، تاریخ، labelIds را برمی‌گرداند. THREAD_VIEW_METADATA_ONLY شناسه، از، به، cc، تاریخ، labelIds را برمی‌گرداند.

نمای موضوع

Enum برای کنترل فیلدهای پر شده برای نخ‌ها در پاسخ‌های ListThreads و SearchThreads.

انوم‌ها
THREAD_VIEW_UNSPECIFIED برای سازگاری با نسخه‌های قبلی، به THREAD_VIEW_MINIMAL نگاشت می‌شود.
THREAD_VIEW_METADATA_ONLY شناسه، از، به، cc، تاریخ، labelIds را برمی‌گرداند.
THREAD_VIEW_MINIMAL شناسه، قطعه کد، موضوع، از، به، رونوشت، تاریخ، شناسه‌های برچسب را برمی‌گرداند.

طرحواره خروجی

پیام پاسخ برای RPC مربوط به SearchThreads.

جستجوموضوعاتپاسخ

نمایش 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)

تعداد نتایج تخمینی برای این پرس‌وجو. باید به عنوان یک حد پایین در نظر گرفته شود، بنابراین برای مثال اگر ۵۰۰ باشد، می‌توان تعداد را به صورت "۵۰۰+" به کاربر گزارش داد.

موضوع

نمایش 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

آدرس‌های ایمیل گیرنده‌ی CC.

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 .

پیوستفراداده

نمایش JSON 
{
  "id": string,
  "mimeType": string,
  "filename": string
}
فیلدها
id

string

فقط خروجی. شناسه پیوست.

mimeType

string

نوع MIME پیوست.

filename

string

نام فایل پیوست.

حاشیه‌نویسی ابزار

راهنمایی مخرب: ❌ | راهنمایی بی‌اثر: ✅ | راهنمایی فقط خواندنی: ✅ | راهنمایی جهان باز: ❌

دامنه‌های مجوز

به یکی از حوزه‌های OAuth زیر نیاز دارد:

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