MCP Tools Reference: gmailmcp.googleapis.com

ابزار: get_message

یک پیام ایمیل خاص را از حساب Gmail کاربر احراز هویت شده با استفاده از شناسه پیام منحصر به فرد آن بازیابی می‌کند.

از این ابزار برای بررسی یک ایمیل واحد و مجزا، زمانی که شناسه پیام آن را می‌دانید، استفاده کنید. اگر کاربر می‌خواهد یک ایمیل خاص را با جزئیات بخواند، متن دقیق یک پیام را بررسی کند یا فراداده‌های پیوست یک ایمیل واحد را بررسی کند، این ابزار مناسب است. این ابزار برای بازیابی کل مکالمات یا مشاهده رشته‌های بحث و گفتگو مناسب نیست؛ به جای آن از ابزار 'get_thread' استفاده کنید. شاخص‌های کلیدی شامل این است که آیا کاربر محتوای کامل یک شناسه پیام خاص را که توسط جستجوی قبلی برگردانده شده است، درخواست می‌کند یا اگر پرس و جو درخواست بررسی یک ایمیل خاص به جای کل رشته را دارد. به عنوان مثال، درخواست‌های کاربر عبارتند از: "متن کامل شناسه پیام 18f123456789abcd را دریافت کنید."، "آخرین پیام در آن رشته از آلیس را بخوانید." و "نام پیوست‌ها در ایمیلی که من از HR دریافت کرده‌ام چیست؟"

پارامتر اختیاری messageFormat قالب پیام برگشتی را کنترل می‌کند. به طور پیش‌فرض (یا با FULL_CONTENT )، محتوای کامل پیام را برمی‌گرداند. MINIMAL برای درج فقط موضوع و قطعه کد (به استثنای بدنه) استفاده کنید. از METADATA_ONLY برای درج فقط فراداده‌های اولیه (شناسه پیام، شناسه رشته، برچسب‌ها، مهر زمانی و تخمین اندازه) استفاده کنید.

مثال زیر نحوه استفاده از curl برای فراخوانی ابزار get_message 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": "get_message",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

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

درخواست پیام برای GetMessage RPC.

درخواست دریافت پیام

نمایش JSON 
{
  "messageId": string,
  "messageFormat": enum (MessageFormat)
}
فیلدها
messageId

string

الزامی. شناسه منحصر به فرد پیامی که قرار است دریافت شود.

messageFormat

enum ( MessageFormat )

اختیاری. قالب پیام برگشتی را مشخص می‌کند. مقدار پیش‌فرض FULL_CONTENT است.

قالب پیام

Enum برای کنترل سطح جزئیات پیام‌های موجود در رشته.

انوم‌ها
MESSAGE_FORMAT_UNSPECIFIED مقدار پیش‌فرض FULL_CONTENT است.
MINIMAL قطعه‌های پیام و سرصفحه‌های کلیدی (موضوع، از، به، رونوشت، تاریخ) را برمی‌گرداند.
FULL_CONTENT تمام اطلاعات موجود در "MINIMAL" به علاوه‌ی محتوای کامل بدنه‌ی هر پیام را برمی‌گرداند.
METADATA_ONLY فقط فراداده: شامل نام فایل‌های موضوع، قطعه کد، بدنه و پیوست نمی‌شود.

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

پیام درون یک تاپیک.

پیام

نمایش 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
  • https://www.googleapis.com/auth/gmail.metadata