پیکربندی سرور MCP در Gmail

Gmail یک سرور راه دور Model Context Protocol (MCP) ارائه می‌دهد که به عامل‌های هوشواره‌ای امکان می‌دهد به‌طور ایمن با داده‌های Gmail تعامل داشته باشند. با پیکربندی سرور MCP Gmail، به برنامه‌های هوش مصنوعی مثل Google Antigravity و Claude امکان می‌دهید کنش‌هایی را در Gmail انجام دهند.

سرور MCP ‏Gmail روشی استاندارد برای عامل‌های هوش مصنوعی فراهم می‌کند تا:

  • خواندن داده‌ها: جستجوی ایمیل‌ها، بازیابی رشته‌ها، و فهرست کردن برچسب‌ها.
  • اقدام کردن: پیش‌نویس ایمیل ایجاد کنید و پیام‌ها را برچسب‌گذاری کنید.
  • رعایت امنیت: همان اجازه‌ها و کنترل‌های حاکمیت داده کاربر را به ارث می‌برد.

پیش‌نیازها

پیکربندی سرور MCP در Gmail

برای استفاده از سرور MCP در Gmail، باید آن را در پروژه Google Cloud خود فعال کنید و سپس کارخواه MCP خود را برای اتصال به آن پیکربندی کنید.

فعال کردن میاناهای برنامه‌سازی کاربردی

برای استفاده از سرور Gmail MCP، باید API زیر را در پروژه Google Cloud خود فعال کنید:

  • Gmail API

CLI

gcloud services enable gmail.googleapis.com --project=PROJECT_ID

PROJECT_ID را با شناسه پروژه Google Cloud خودتان جایگزین کنید.

کنسول

میاناهای برنامه‌سازی کاربردی را در کنسول Google Cloud فعال کنید:

فعال کردن میاناهای برنامه‌سازی کاربردی

فعال کردن سرویس‌های MCP

برای فعال کردن مؤلفه‌های MCP برای Gmail، باید سرویس زیر را در پروژه Google Cloud خود فعال کنید:

  • Gmail MCP API

CLI

gcloud services enable gmailmcp.googleapis.com --project=PROJECT_ID

PROJECT_ID را با شناسه پروژه Google Cloud خودتان جایگزین کنید.

کنسول

سرویس‌های MCP را در کنسول Google Cloud فعال کنید:

فعال کردن سرویس‌های MCP

سرور MCP‏ Gmail از OAuth 2.0 برای اصالت‌سنجی و مجوزدهی استفاده می‌کند. قبل‌از اینکه بتوانید شناسه کارخواه OAuth ایجاد کنید، باید صفحه کسب رضایت OAuth را پیکربندی کنید.

  1. در کنسول Google Cloud، به پلاتفرم Google Auth > نمانام‌سازی بروید.

    رفتن به نمانام‌سازی

  2. اگر قبلاً پلاتفرم Google Auth را پیکربندی کرده‌اید، می‌توانید تنظیمات «صفحه رضایت OAuth» زیر را در نمانام‌سازی، مخاطب، و دسترسی به داده پیکربندی کنید. اگر پیامی دیدید که می‌گوید پلاتفرم Google Auth هنوز پیکربندی نشده است، روی شروع به کار کلیک کنید:

    1. در بخش اطلاعات برنامه، در نام برنامه، Gmail MCP Server را تایپ کنید.
    2. در ایمیل پشتیبانی کاربر، نشانی ایمیل خودتان یا «گروه Google» مناسبی را انتخاب کنید.
    3. روی بعدی کلیک کنید.
    4. در بخش مخاطبان، داخلی را انتخاب کنید. اگر نمی‌توانید داخلی را انتخاب کنید، خارجی را انتخاب کنید.
    5. روی بعدی کلیک کنید.
    6. در بخش اطلاعات تماس، نشانی ایمیلی را وارد کنید که بتوانید ازطریق آن از هرگونه تغییر در پروژه‌تان مطلع شوید.
    7. روی بعدی کلیک کنید.
    8. در بخش پایان، خط‌مشی داده‌های کاربر سرویس‌های Google API را مرور کنید و اگر موافقید، با «خط‌مشی داده‌های کاربر سرویس‌های Google API» موافقم را انتخاب کنید.
    9. روی ادامه کلیک کنید.
    10. روی ایجاد کردن کلیک کنید.
    11. اگر خارجی را برای نوع کاربر انتخاب کرده‌اید، کاربران آزمایشی را اضافه کنید:
      1. روی مخاطبان کلیک کنید.
      2. در بخش کاربران آزمایشی، روی افزودن کاربران کلیک کنید.
      3. نشانی ایمیل خودتان و هر کاربر آزمایشی مجاز دیگری را وارد کنید، سپس روی ذخیره کلیک کنید.

  3. روی دسترسی به داده‌ها > افزودن یا برداشتن دامنه‌ها کلیک کنید. پانلی با فهرستی از دامنه‌ها برای هر میانای برنامه‌سازی کاربردی که در پروژه Google Cloud فعال کرده‌اید نشان داده می‌شود.

    1. در بخش افزودن دستی دامنه‌ها، دامنه‌های سرور MCP‏ Gmail را جای‌گذاری کنید:

      • https://www.googleapis.com/auth/gmail.readonly
      • https://www.googleapis.com/auth/gmail.compose

    2. روی افزودن به جدول کلیک کنید.

    3. روی به‌روزرسانی کلیک کنید.

    4. پس‌از انتخاب کردن دامنه‌های موردنیاز برنامه‌تان، در صفحه دسترسی به داده، روی ذخیره کلیک کنید.

پیکربندی کردن کارخواه MCP

برای افزودن سرور MCP راه دور Gmail به کارخواه MCP، دستورالعمل‌های کارخواه خود را دنبال کنید.

شناسه‌های کارخواه OAuth 2.0 واگذارشده به کاربر که سرور MCP‏ Gmail را فراخوانی می‌کنند باید گزینه از این کارخواه برای عامل مجهز به هوش مصنوعی استفاده شود را در پلاتفرم Google Auth > کارخواه‌ها انتخاب کرده باشند. برای به‌روزرسانی شناسه کارخواه OAuth 2.0 موجود، این تنظیم را در پلاتفرم Google Auth > کارخواه‌ها انتخاب کنید، همان‌طور که در مدیریت کارخواه‌های OAuth شرح داده شده است. اگر نمی‌توانید این تنظیم را در کارخواه موجود تغییر دهید، یا اگر کارخواه از ویژگی‌های غیرعامل نیز پشتیبانی می‌کند، شناسه کارخواه OAuth 2.0 جدیدی برای عامل هوش مصنوعی خود ایجاد کنید. برای درخواست‌های ردشده، حساب‌های سرویس با واگذاری در سراسر دامنه، یا Google Apps Script، به عیب‌یابی مراجعه کنید.

Antigravity

برای افزودن سرور MCP راه دور Gmail به Antigravity، پیکربندی سرور را به فایل mcp_config.json خود اضافه کنید. این دستورالعمل‌ها از Antigravity 2.0،‏ Antigravity IDE، و Antigravity CLI پشتیبانی می‌کنند.

  1. شناسه و رمز کارخواه OAuth 2.0 ایجاد کنید:

    1. در کنسول Google Cloud، به پلاتفرم Google Auth > کارخواه‌ها > ایجاد کارخواه بروید.

      رفتن به «ایجاد کارخواه»

    2. برنامه وب را به‌عنوان نوع برنامه انتخاب کنید.

    3. نام را وارد کنید.

    4. در بخش شناسه‌های URI هدایت مجاز، روی + افزودن شناسه URI کلیک کنید، سپس https://antigravity.google/oauth-callback را در فیلد شناسه‌های URI اضافه کنید.

    5. استفاده از این کارخواه برای عامل مجهز به هوش مصنوعی را انتخاب کنید.

    6. روی ایجاد کلیک کنید و شناسه کارخواه و رمز کارخواه خود را کپی کنید.

  2. فایل پیکربندی را باز یا ایجاد کنید ~/.gemini/config/mcp_config.json.

  3. پیکربندی mcpServers را به mcp_config.json اضافه کنید:

    {
  "mcpServers": {
    "gmail": {
      "serverUrl": "https://gmailmcp.googleapis.com/mcp/v1",
      "oauth": {
        "clientId": "OAUTH_CLIENT_ID",
        "clientSecret": "OAUTH_CLIENT_SECRET"
      }
    }
  }
}

    موارد زیر را جایگزین کنید:

    • ‫OAUTH_CLIENT_ID: شناسه کارخواهی که ایجاد کردید.
    • ‫OAUTH_CLIENT_SECRET: رمز کارخواهی که ایجاد کردید.

  4. ‫mcp_config.json صرفه‌جویی کنید.

  5. سرور MCP را اصالت‌سنجی کنید. می‌توانید بااستفاده از تنظیمات GUI یا CLI اصالت‌سنجی کنید:

    • برای Antigravity IDE یا GUI‏ (Antigravity 2.0):

      1. صفحه تنظیمات را باز کنید (مثلاً روی تنظیمات در پایین سمت راست کلیک کنید یا تنظیمات کاربر Antigravity را باز کنید).
      2. به سفارشی‌سازی‌ها بروید.
      3. در بخش سرورهای MCP نصب‌شده، روی بازآوری کلیک کنید.
      4. gmail را در فهرست پیدا کنید، روی اصالت‌سنجی کلیک کنید، به سیستم «حساب Google» خود وارد شوید، کد مجوز را کپی کنید، آن را در کادر گفتگوی ورودی جای‌گذاری کنید، و روی ارسال کلیک کنید.

    • برای Antigravity CLI:

      1. شروع کردن Antigravity CLI:

        agy

      2. با اجرای دستور زیر، پانل مدیریت تعاملی MCP را باز کنید:

        /mcp

      3. بااستفاده از کلیدهای جهت‌نما، gmail را انتخاب کنید، به کنش اصالت‌سنجی بروید، و کلید ورود را فشار دهید. جریان ورود به سیستم را در مرورگرتان تکمیل کنید، کد مجوز را کپی کنید، آن را در پیام‌واره پایانه جای‌گذاری کنید، و کلید ورود را فشار دهید.

  6. تأیید کنید که سرور به‌درستی پیکربندی شده است و کار می‌کند:

    • برای Antigravity IDE یا GUI: دکمه خروج از سیستم در کنار سرور در بخش سفارشی‌سازی‌ها > سرورهای MCP نصب‌شده ظاهر می‌شود.
    • برای Antigravity CLI: پانل /mcp را باز کنید تا سرورهای MCP پیکربندی‌شده‌تان را ببینید. سرورهای درستی‌سنجی‌شده و اصالت‌سنجی‌شده اصالت‌سنجی‌شده را در کنار نامشان در پانل TUI تعاملی نمایش می‌دهند. می‌توانید هر سروری را در نمای داشبورد انتخاب کنید تا وضعیت آن را بررسی کنید و همه ابزارهای دردسترس آن را فهرست کنید.

سرور MCP راه دور برای استفاده در Antigravity آماده است.

Claude

برای استفاده از سرور MCP ازراه‌دور Gmail با Claude.ai یا Claude Desktop، باید طرح Claude Enterprise،‏ Pro،‏ Max، یا Team داشته باشید.

برای افزودن سرور MCP راه دور Gmail به Claude، یک متصل‌کننده سفارشی با شناسه و رمز کارخواه OAuth پیکربندی کنید.

  1. شناسه و رمز کارخواه OAuth 2.0 ایجاد کنید:

    1. در کنسول Google Cloud، به پلاتفرم Google Auth > کارخواه‌ها > ایجاد کارخواه بروید.

      رفتن به «ایجاد کارخواه»

    2. برنامه وب را به‌عنوان نوع برنامه انتخاب کنید.

    3. نام را وارد کنید.

    4. در بخش شناسه‌های URI هدایت مجاز، روی + افزودن شناسه URI کلیک کنید، سپس https://claude.ai/api/mcp/auth_callback را در فیلد شناسه‌های URI اضافه کنید.

    5. استفاده از این کارخواه برای عامل مجهز به هوش مصنوعی را انتخاب کنید.

    6. روی ایجاد کلیک کنید و شناسه کارخواه و رمز کارخواه خود را کپی کنید.

  2. سرور MCP را در Claude پیکربندی کنید:

    1. در Claude.ai یا Claude Desktop، به تنظیمات > رابط‌ها یا تنظیمات سرپرست > رابط‌ها بروید.
    2. روی افزودن متصل‌کننده سفارشی کلیک کنید.
    3. جزئیات اتصال را برای محصول Gmail وارد کنید:
      • نام سرور: Gmail.
      • نشانی وب سرور MCP راه دور: https://gmailmcp.googleapis.com/mcp/v1
    4. در تنظیمات پیشرفته، شناسه کارخواه OAuth و رمز کارخواه OAuth را وارد کنید.
    5. روی افزودن کلیک کنید.

موارد دیگر

بسیاری از برنامه‌های هوش مصنوعی روش‌هایی برای متصل شدن به سرور MCP ازراه‌دور دارند. معمولاً باید جزئیات مربوط به سرور را وارد کنید، مانند نام، نقاط پایانی، پروتکل انتقال، و روش اصالت‌سنجی. برای سرور MCP راه دور Gmail، موارد زیر را وارد کنید:

  • نام سرور: gmail

  • نشانی وب سرور: https://gmailmcp.googleapis.com/mcp/v1

  • انتقال: HTTP جاری‌سازی‌پذیر

  • اصالت‌سنجی: سرور MCP راه دور Gmail از OAuth 2.0 استفاده می‌کند. هنگام ایجاد کارخواه OAuth 2.0، استفاده از این کارخواه برای عامل مجهز به هوش مصنوعی را انتخاب کنید. برای جزئیات، به آشنایی با اصالت‌سنجی و صدور مجوز مراجعه کنید.

برای جزئیات بیشتر درباره متصل کردن انواع مختلف کارخواه‌ها، پیکربندی MCP در برنامه هوش مصنوعی را ببینید.

آزمایش کردن سرور Gmail MCP

پس‌از پیکربندی کردن کارخواه MCP، می‌توانید با اجرای چند پیام‌واره آزمایشی، اتصال را درستی‌سنجی کنید.

سؤالات زیر را از کارخواه MCP خود بپرسید:

  • «آریل در آخرین ایمیلش درباره طرح بازاریابی ما چه گفت؟»

    کارخواه ایمیل‌های دریافتی از Ariel را بااستفاده از gmail.search_threads فیلتر می‌کند، محتوای جدیدترین رشته را با gmail.get_thread بازیابی می‌کند، و سپس آن را برای شما خلاصه می‌کند.

  • «ایمیلی به ariel@example.com پیش‌نویس کن و بگو که طرح بازاریابی را تأیید می‌کنم.»

    کارخواه از gmail.create_draft برای ایجاد ایمیل در پوشه پیش‌نویس‌های شما استفاده می‌کند، که به شما امکان می‌دهد آن را از Gmail بررسی و ارسال کنید.

اگر ابزارها با موفقیت اجرا شوند و پاسخ‌های مرتبط دریافت کنید، سرور MCP Gmail شما به‌درستی پیکربندی شده است.

عیب‌یابی

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

بررسی رویدادهای گزارش OAuth

اگر در اتصال به سرور MCP با مشکلی مواجه شدید، گزارش‌های OAuth را برای یافتن خطا بررسی کنید. از سرپرست Google Workspace خود بخواهید رویدادهای ثبت OAuth را در ابزار بررسی امنیتی بازبینی کند.

درخواست‌های ردشده از کارخواه‌های OAuth واگذارشده به کاربر

اگر درخواست‌های شما به سرور MCP رد می‌شود، مطمئن شوید که شناسه کارخواه OAuth 2.0 واگذارشده به کاربر برای جریان OAuth سه‌پایه شما، گزینه از این کارخواه برای نماینده مجهز به هوش مصنوعی استفاده شود را در پلاتفرم اصالت‌سنجی Google > کارخواه‌ها انتخاب کرده باشد:

  • کارخواه موجود از این تنظیم پشتیبانی می‌کند: استفاده از این کارخواه برای نماینده مجهز به هوش مصنوعی را در کارخواه OAuth موجودتان انتخاب کنید.
  • کارخواه موجود به‌روز نمی‌شود: کارخواه OAuth جدیدی ایجاد کنید و استفاده از این کارخواه برای عامل مجهز به هوش مصنوعی را انتخاب کنید و برنامه‌تان را به‌روز کنید تا از آن استفاده کند.
  • کارخواه موجود از ویژگی‌های غیرعامل نیز پشتیبانی می‌کند: کارخواه OAuth جداگانه‌ای برای عامل هوش مصنوعی ایجاد کنید و کارخواه موجود را برای ویژگی‌های غیرعامل خود نگه دارید.

برای دستورالعمل‌ها، به پیکربندی کارخواه MCP و مدیریت کارخواه‌های OAuth مراجعه کنید.

حساب‌های سرویس با تفویض اختیار در سراسر دامنه

اگر برنامه‌تان از حساب سرویس با تفویض اختیار در سراسر دامنه برای OAuth دوطرفه استفاده می‌کند، نمی‌توانید از این کارخواه برای نماینده مجهز به هوش مصنوعی استفاده کنید را انتخاب کنید زیرا حساب‌های سرویس در پلاتفرم Google Auth > کارخواه‌ها مدیریت نمی‌شوند:

  • کنترل دسترسی: درخواست‌های ارسال‌شده به سرور MCP از این حساب‌های سرویس به‌دلیل نداشتن تنظیمات عامل رد نمی‌شوند. درعوض، دسترسی توسط تنظیمات واگذاری سراسری دامنه که سرپرست Google Workspace شما مدیریت می‌کند کنترل می‌شود. برای جزئیات مربوط به تنظیمات سرپرست، کنترل دسترسی به API با واگذاری سراسر دامنه را ببینید.
  • کنش‌های حساس: سرورهای MCP در Google Workspace همچنان پیام‌واره‌های استخراج فرم را برای تأیید مشارکت انسانی در حلقه در فراخوانی‌های ابزار حساس که ازطریق جعل هویت کاربر واگذاری در سراسر دامنه انجام می‌شوند برمی‌گردانند.

درخواست‌ها از Apps Script

اگر سرور MCP را از Apps Script فراخوانی کنید، نمی‌توانید از این کارخواه برای نماینده مجهز به هوش مصنوعی استفاده کنید را در کارخواه OAuth پیش‌فرضی که Apps Script برای اسکریپت شما ایجاد و مدیریت می‌کند انتخاب کنید. این موضوع حتی اگر دست‌نوشته شما از پروژه استاندارد Google Cloud استفاده کند نیز اعمال می‌شود.

برای فراخوانی سرور MCP از Apps Script، کارهای زیر را انجام دهید:

  1. در کنسول Google Cloud، به پلاتفرم Google Auth > کارخواه‌ها بروید، یک کارخواه OAuth ایجاد کنید، و استفاده از این کارخواه برای نماینده مجهز به هوش مصنوعی را انتخاب کنید.
  2. در اسکریپت خود، از OAuth2 برای Apps Script کتابخانه برای مجوز دادن به کاربران با آن کارخواه OAuth استفاده کنید.
  3. وقتی سرور MCP را فراخوانی می‌کنید، کد دسترسی را که کتابخانه برمی‌گرداند به‌جای کد از ScriptApp.getOAuthToken ارسال کنید.

پروژه‌های Apps Script که سرورهای MCP در Google Workspace را فراخوانی نمی‌کنند تحت‌تأثیر قرار نمی‌گیرند.

پیام‌واره‌های ورود به سیستم تکراری ساعتی

اگر تقریباً هر ساعت از شما خواسته می‌شود دوباره به سیستم وارد شوید، کارخواه MCP شما ژتون بازآوری دریافت نمی‌کند. سرور Google OAuth 2.0 فقط زمانی کد بازآوری صادر می‌کند که درخواست مجوز شامل access_type=offline باشد. درخواست کردن فقط گستره offline_access OpenID Connect (OIDC) چیزی برنمی‌گرداند.

بررسی کنید که آیا کارخواه MCP شما از پارامترهای مجوز سفارشی پشتیبانی می‌کند یا نه:

  • کارخواه از پارامترهای مجوز سفارشی پشتیبانی می‌کند: access_type=offline را به درخواست مجوز اضافه کنید. برای دریافت ژتون بازآوری جدید برای کاربری که قبلاً دسترسی اعطا کرده است، prompt=consent را نیز اضافه کنید.
  • کارخواه از پارامترهای مجوز سفارشی پشتیبانی نمی‌کند: هربار که کد دسترسی منقضی می‌شود، دوباره به سیستم وارد شوید.

برای جزئیات، به بازآوری کد دسترسی مراجعه کنید.

مرجع ابزار

ابزارهای زیر برای سرور MCP در Gmail دردسترس است:

  • create_draft
  • get_thread
  • label_message
  • label_thread
  • list_drafts
  • list_labels
  • search_threads
  • unlabel_message
  • unlabel_thread

ملاحظه امنیتی مهم: تزریق پیام‌واره غیرمستقیم

وقتی مدل زبانی را درمعرض داده‌های غیرقابل‌اعتماد قرار می‌دهید، خطر حمله تزریق پیام‌واره غیرمستقیم وجود دارد. چون میزبان‌های MCP مثل Google Antigravity ازطریق سرور MCP‏ Gmail به ابزارها و APIهای قدرتمند دسترسی دارند، می‌توانند داده‌های «حساب Google» شما را بخوانند، اصلاح کنند، و حذف کنند.

برای کاهش این خطرات، باید پیام‌واره‌ها و پاسخ‌ها را ازنظر محتوای مخرب یا حملات تزریق پیام‌واره غربال کنید. می‌توانید از Model Armor ارائه‌شده توسط Google استفاده کنید یا می‌توانید از راهکار خودتان استفاده کنید، به‌شرطی که آن را مستند کنید تا کاربران بتوانند آن ریسک را بپذیرند. برای اطلاعات بیشتر، پیکربندی امنیت برای سرورهای MCP در Google Workspace را ببینید.

این روال‌های مطلوب را دنبال کنید:

  • فقط از ابزارهای مورداعتماد استفاده کنید. هرگز سرور MCP‏ Gmail را به برنامه‌های غیرقابل‌اعتماد یا تأییدنشده متصل نکنید.
  • دربرابر ورودی‌های غیرقابل‌اعتماد احتیاط کنید. از کارخواه MCP خود نخواهید که ایمیل‌ها یا منابع دیگر را از منابع تأییدنشده پردازش کند. این ورودی‌ها ممکن است حاوی دستورالعمل‌های پنهانی باشند که می‌توانند جلسه شما را بربایند، و به مهاجم اجازه دهند داده‌های شما را تغییر دهد، سرقت کند، یا حذف کند.
  • همه کنش‌ها را مرور کنید. همیشه کنش‌هایی را که مشتری هوش مصنوعی ازجانب شما انجام می‌دهد به‌دقت بازبینی کنید تا مطمئن شوید درست هستند و با اهداف شما مطابقت دارند.