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

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

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

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

پیش‌نیازها

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

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

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

برای استفاده از سرور MCP در Gmail، میانای برنامه‌سازی کاربردی زیر را در پروژه 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
      • https://www.googleapis.com/auth/gmail.modify
    2. روی افزودن به جدول کلیک کنید.

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

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

پیکربندی برنامه هوش مصنوعی

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

شناسه‌های کارخواه 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، استفاده از این کارخواه برای عامل مجهز به هوش مصنوعی را انتخاب کنید. برای جزئیات، به آشنایی با اصالت‌سنجی و صدور مجوز مراجعه کنید.

    برای جلوگیری از پیام‌واره‌های ورود به سیستم ساعتی با کارخواه OAuth برنامه وب، کارخواه MCP خود را پیکربندی کنید تا بااستفاده از access_type=offline یا گستره offline_access، دسترسی آفلاین درخواست کند. برای جزئیات بیشتر، پیام‌واره‌های ورود به سیستم ساعتی تکراری را ببینید.

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

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

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

سؤالات زیر را از برنامه هوش مصنوعی بپرسید:

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

    کارخواه ایمیل‌های 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 جداگانه برای عامل هوش مصنوعی ایجاد کنید و کارخواه موجود را برای ویژگی‌های غیرعامل خود نگه دارید.

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

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

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

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

درخواست‌ها از 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 شما ژتون بازآوری را دریافت یا استفاده نمی‌کند. این اتفاق معمولاً در شرایط زیر رخ می‌دهد:

  • دسترسی آفلاین در کارخواه OAuth برنامه وب وجود ندارد: برخلاف کارخواه‌های OAuth برنامه رایانه‌ای، کارخواه‌های OAuth برنامه وب به‌طور پیش‌فرض دسترسی آنلاین دارند. برای درخواست ژتون بازآوری، access_type=offline را اضافه کنید یا offline_access OpenID Connect (OIDC)‎ را در کنار حداقل یک دامنه API اضافه کنید و access_type=online را تنظیم نکنید.
  • صدور مجدد مجوز برای برنامه‌ای که قبلاً با آن موافقت شده است: سرور OAuth 2.0 Google اولین باری که کاربر دسترسی آفلاین اعطا می‌کند، یک ژتون بازآوری صادر می‌کند. اگر کاربری قبلاً کارخواه OAuth شما را بدون دسترسی آفلاین مجاز کرده باشد، یا اگر کارخواه MCP شما ژتون بازآوری ذخیره‌شده خود را ازدست داده باشد، ممکن است ورودهای بعدی به سیستم ژتون بازآوری جدیدی برنگرداند. prompt=consent را در درخواست مجوز اضافه کنید، یا دسترسی برنامه را در اتصال‌های «حساب Google» بردارید و دوباره به سیستم وارد شوید.
  • رمزیاب دارنده ثابت: اگر کد دسترسی خام را در سرصفحه Authorization ارسال کنید، مثلاً خروجی از gcloud auth print-access-token، رمزیاب پس‌از یک ساعت منقضی می‌شود مگراینکه کارخواه شما آن را بازآوری کند.

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

مرجع ابزار

ابزارهای زیر برای سرور MCP در Gmail دردسترس است. برای طرح‌واره‌های ورودی و خروجی، به مرجع Gmail MCP مراجعه کنید:

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

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

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

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

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