با Google Workspace MCP و Gemini CLI شروع کنید

۱. مقدمه

در این آزمایشگاه کد، یاد خواهید گرفت که چگونه از پروتکل Model Context (MCP) برای اتصال Gemini CLI به داده‌های Google Workspace خود استفاده کنید. MCP یک استاندارد باز است که مدل‌های هوش مصنوعی را قادر می‌سازد تا به طور ایمن از ابزارهای ارائه شده توسط سرورهای راه دور استفاده کنند. شما از Gemini CLI به عنوان کلاینت خود برای تعامل با Gmail، Google Drive، Google Calendar، Google Chat و People API بدون نوشتن هیچ کدی استفاده خواهید کرد!

کاری که انجام خواهید داد

• سرویس‌های Google Workspace MCP را در پروژه Google Cloud خود فعال کنید.
• رابط خط فرمان Gemini را برای استفاده از این سرویس‌های MCP پیکربندی کنید.
• ادغام را با پیام‌های سرگرم‌کننده و مفیدی که با داده‌های Google Workspace شما تعامل دارند، آزمایش کنید.

آنچه نیاز دارید

• یک مرورگر وب مانند کروم
• یک پروژه ابری گوگل
• یک حساب کاربری گوگل ورک اسپیس
• Gemini CLI روی دستگاه محلی شما نصب شده باشد

تکمیل این آزمایشگاه کد تقریباً 30 دقیقه طول خواهد کشید.

دسترسی آسان به این آزمایشگاه کد

۲. قبل از شروع

برنامه پیش‌نمایش توسعه‌دهندگان Google Workspace: دسترسی به سرورهای Google Workspace MCP بخشی از برنامه پیش‌نمایش توسعه‌دهندگان عمومی است. اگر قبلاً این کار را نکرده‌اید، لطفاً در https://developers.google.com/workspace/preview ثبت‌نام کنید و مطمئن شوید که حساب شما در این برنامه پذیرفته شده است.

یک پروژه Google Cloud ایجاد یا انتخاب کنید

در کنسول گوگل کلود ، یک پروژه گوگل کلود انتخاب یا ایجاد کنید .

فعال کردن APIها

برای استفاده از سرورهای MCP گوگل ورک‌اسپیس، باید APIهای استاندارد گوگل ورک‌اسپیس را فعال کنید. در حالی که برخی از سرورهای MCP به طور مستقل عمل می‌کنند، برخی دیگر همچنان نیاز به فعال بودن API استاندارد زیرین دارند:

• جیمیل و چت هنوز به API های استاندارد خود نیاز دارند.
• درایو برای ابزارهای خاص به API استاندارد نیاز دارد.
• تقویم نیازی به فعال بودن API استاندارد ندارد.
• رابط برنامه‌نویسی کاربردی افراد (People API) هم دسترسی استاندارد و هم قابلیت MCP را مدیریت می‌کند، بنابراین سرویس MCP جداگانه‌ای برای فعال‌سازی ندارد.

فعال کردن APIها

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

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

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

پیکربندی برنامه چت

برای استفاده از سرور Google Chat MCP، باید یک برنامه چت را در پروژه Google Cloud خود پیکربندی کنید.

1. در کنسول گوگل کلود، عبارت Google Chat API را جستجو کنید و روی Google Chat API > Manage > Configuration کلیک کنید. به Google Chat API بروید
2. برنامه چت را تنظیم کنید:
   • در فیلد نام برنامه ، Chat MCP را وارد کنید.
   • در قسمت آدرس اینترنتی آواتار ، آدرس https://developers.google.com/chat/images/quickstart-app-avatar.png را وارد کنید.
   • در قسمت توضیحات ، Chat MCP server را وارد کنید.
   • در بخش عملکرد (Functionality) ، با فعال کردن گزینه‌ی غیرفعال کردن فعال‌سازی ویژگی‌های تعاملی، ویژگی‌های تعاملی را غیرفعال کنید.
   • در قسمت گزارش‌ها ، گزینه ثبت خطاها را برای ثبت گزارش‌ها انتخاب کنید.
3. روی ذخیره کلیک کنید.

۳. پیکربندی OAuth Consent و Client

سرورهای Google Workspace MCP از OAuth 2.0 برای احراز هویت امن استفاده می‌کنند. شما باید یک صفحه رضایت OAuth پیکربندی کنید و یک کلاینت برنامه دسکتاپ ایجاد کنید.

صفحه رضایت OAuth را تنظیم کنید

سرورهای Google Workspace MCP از OAuth 2.0 برای احراز هویت استفاده می‌کنند. ابتدا باید صفحه رضایت را پیکربندی کنید.

1. در کنسول گوگل کلود، به Google Auth Platform > Branding بروید. اگر پیکربندی نشده است، روی Get Started کلیک کنید.
2. پیکربندی اطلاعات برنامه :
   • نام برنامه : Google Workspace MCP Servers
   • ایمیل پشتیبانی کاربر : ایمیل خود را انتخاب کنید.
3. پیکربندی مخاطب : داخلی (یا خارجی اگر داخلی در دسترس نیست) را انتخاب کنید.
4. پیکربندی اطلاعات تماس : آدرس ایمیل خود را وارد کنید.
5. سیاست داده‌های کاربر را مرور و با آن موافقت کنید، سپس روی ایجاد کلیک کنید.
6. اگر گزینه‌ی خارجی (External) را انتخاب کرده‌اید، به بخش مخاطبان (Audience) بروید و ایمیل خود را در بخش کاربران آزمایشی (Test users) اضافه کنید.
7. به Data Access > Add or Remove Scopes بروید. در قسمت Manually add scopes ، موارد زیر را برای سرورهایی که می‌خواهید استفاده کنید، اضافه کنید:
   • تقویم گوگل : https://www.googleapis.com/auth/calendar.calendarlist.readonly ، https://www.googleapis.com/auth/calendar.events.freebusy ، https://www.googleapis.com/auth/calendar.events.readonly
   • گوگل چت : https://www.googleapis.com/auth/chat.spaces.readonly ، https://www.googleapis.com/auth/chat.memberships.readonly ، https://www.googleapis.com/auth/chat.messages.readonly ، https://www.googleapis.com/auth/chat.users.readstate.readonly
   • گوگل درایو : https://www.googleapis.com/auth/drive.readonly ، https://www.googleapis.com/auth/drive.file
   • جیمیل : https://www.googleapis.com/auth/gmail.readonly ، https://www.googleapis.com/auth/gmail.compose
   • رابط برنامه‌نویسی کاربردی افراد : https://www.googleapis.com/auth/directory.readonly ، https://www.googleapis.com/auth/userinfo.profile ، https://www.googleapis.com/auth/contacts.readonly
8. روی افزودن به جدول ، سپس به‌روزرسانی و در نهایت ذخیره کلیک کنید.

یک شناسه کلاینت OAuth ایجاد کنید

1. به پلتفرم احراز هویت گوگل > کلاینت‌ها > ایجاد کلاینت بروید.
2. نوع برنامه را روی Desktop app انتخاب کنید.
3. نام آن را Gemini CLI بگذارید.
4. روی Create کلیک کنید و Client ID و Client Secret را کپی کنید. در مرحله بعدی به این موارد نیاز خواهید داشت.

۴. پیکربندی رابط خط فرمان Gemini

حالا بیایید رابط خط فرمان Gemini را برای استفاده از این نقاط پایانی پیکربندی کنیم. اگر رابط خط فرمان Gemini را نصب ندارید، دستورالعمل‌های نصب را در وب‌سایت رابط خط فرمان Gemini دنبال کنید.

محیط محلی مورد نیاز: برای این مرحله از Cloud Shell استفاده نکنید. رابط خط فرمان Gemini برای احراز هویت OAuth به یک مرورگر محلی نیاز دارد. لطفاً از ترمینال دستگاه محلی خود استفاده کنید. برای اطلاعات بیشتر به الزامات تغییر مسیر مرورگر مراجعه کنید.

فایل پیکربندی را ایجاد کنید

~/.gemini/settings.json را در دایرکتوری خانگی خود باز یا ایجاد کنید و پیکربندی زیر را به آن اضافه کنید. متغیرهای ورودی را با اعتبارنامه‌های OAuth خود جایگزین کنید.

{
  "mcpServers": {
    "calendar": {
      "httpUrl": "https://calendarmcp.googleapis.com/mcp/v1",
      "oauth": {
        "enabled": true,
        "clientId": "<YOUR_CLIENT_ID>",
        "clientSecret": "<YOUR_CLIENT_SECRET>",
        "scopes": [
          "https://www.googleapis.com/auth/calendar.calendarlist.readonly",
          "https://www.googleapis.com/auth/calendar.events.freebusy",
          "https://www.googleapis.com/auth/calendar.events.readonly"
        ]
      }
    },
    "chat": {
      "httpUrl": "https://chatmcp.googleapis.com/mcp/v1",
      "oauth": {
        "enabled": true,
        "clientId": "<YOUR_CLIENT_ID>",
        "clientSecret": "<YOUR_CLIENT_SECRET>",
        "scopes": [
          "https://www.googleapis.com/auth/chat.spaces.readonly",
          "https://www.googleapis.com/auth/chat.memberships.readonly",
          "https://www.googleapis.com/auth/chat.messages.readonly",
          "https://www.googleapis.com/auth/chat.users.readstate.readonly"
        ]
      }
    },
    "drive": {
      "httpUrl": "https://drivemcp.googleapis.com/mcp/v1",
      "oauth": {
        "enabled": true,
        "clientId": "<YOUR_CLIENT_ID>",
        "clientSecret": "<YOUR_CLIENT_SECRET>",
        "scopes": [
          "https://www.googleapis.com/auth/drive.readonly",
          "https://www.googleapis.com/auth/drive.file"
        ]
      }
    },
    "gmail": {
      "httpUrl": "https://gmailmcp.googleapis.com/mcp/v1",
      "oauth": {
        "enabled": true,
        "clientId": "<YOUR_CLIENT_ID>",
        "clientSecret": "<YOUR_CLIENT_SECRET>",
        "scopes": [
          "https://www.googleapis.com/auth/gmail.readonly",
          "https://www.googleapis.com/auth/gmail.compose"
        ]
      }
    },
    "people": {
      "httpUrl": "https://people.googleapis.com/mcp/v1",
      "oauth": {
        "enabled": true,
        "clientId": "<YOUR_CLIENT_ID>",
        "clientSecret": "<YOUR_CLIENT_SECRET>",
        "scopes": [
          "https://www.googleapis.com/auth/directory.readonly",
          "https://www.googleapis.com/auth/userinfo.profile",
          "https://www.googleapis.com/auth/contacts.readonly"
        ]
      }
    }
  }
}

۵. احراز هویت و تأیید اعتبار سرورهای MCP

قبل از اینکه بتوانید از سرورهای MCP استفاده کنید، باید آنها را احراز هویت کرده و از اتصال آنها اطمینان حاصل کنید.

شروع رابط خط فرمان Gemini

برای شروع Gemini CLI، دستور زیر را در ترمینال خود اجرا کنید:

gemini

احراز هویت

با اجرای دستور مربوطه در Gemini CLI، سرویس‌هایی را که می‌خواهید آزمایش کنید، تأیید اعتبار کنید. شما فقط باید سرویس‌هایی را که قصد دارید در این آزمایشگاه کد از آنها استفاده کنید، تأیید اعتبار کنید.

تقویم

/mcp auth calendar

چت

/mcp auth chat

رانندگی

/mcp auth drive

جیمیل

/mcp auth gmail

مردم

/mcp auth people

برای تأیید هر سرویس، دستورالعمل‌های مرورگر خود را دنبال کنید.

تأیید اتصال

تأیید کنید که ابزارها بارگیری و آماده هستند:

/mcp list

باید خروجی را ببینید که نشان می‌دهد سرویس‌ها به همراه ابزارهایشان Ready هستند.

۶. تست سرورهای MCP

اکنون می‌توانید با استفاده از زبان طبیعی با داده‌های Google Workspace خود تعامل داشته باشید. در اینجا چند نمونه از دستورالعمل‌ها برای هر سرویس آورده شده است.

توجه: در دستورات زیر، متغیرهای داخل کروشه (مثلاً [NAME] ، [FILE_NAME] ) را با مقادیر واقعی از داده‌های Google Workspace خود جایگزین کنید.

تقویم گوگل

سعی کنید از Gemini در مورد برنامه‌تان بپرسید:

• «جلسات آینده من این هفته چیست؟»
• «فردا بعد از ظهر وقت آزاد دارم؟»

گوگل چت

سعی کنید از Gemini بخواهید پیام‌ها را جستجو کند:

• «پیام‌هایی که شامل '[KEYWORD]' هستند را در '[SPACE_NAME]' جستجو کنید.»

گوگل درایو

سعی کنید از Gemini بخواهید فایل‌ها را پیدا کند یا بخواند:

• «در گوگل درایو من دنبال فایل‌هایی بگرد که شامل «[کلمه کلیدی]» باشند.»
• «آخرین اسنادی را که ویرایش کرده‌ام فهرست کنید.»
• «محتوای سند «[نام فایل]» من را بخوانید و اهداف اصلی را خلاصه کنید.»

جیمیل

سعی کنید از Gemini بخواهید ایمیل‌های شما را جستجو یا مدیریت کند:

• «۵ ایمیل آخری که دریافت کردم را خلاصه کن.»
• «ایمیلی به آدرس '[EMAIL_ADDRESS]' بنویسید و درخواست به‌روزرسانی پروژه '[PROJECT_NAME]' را داشته باشید.»

رابط برنامه‌نویسی کاربردی افراد

سعی کنید از Gemini در مورد پروفایل یا مخاطبین خود بپرسید:

• «طبق پروفایل گوگل من، اسم من چیست؟»
• «اطلاعات تماس «[نام]» را پیدا کنید.»

ترکیب چندین سرویس

قدرت واقعی MCP زمانی آشکار می‌شود که Gemini وظایف را در چندین سرویس هماهنگ می‌کند. این دستورالعمل‌ها را که قابلیت‌های بین سرویسی را نشان می‌دهند، امتحان کنید:

• «فایل‌های مربوط به به‌روزرسانی‌های مرحله‌ای «[PROJECT_NAME]» را در درایو جستجو کنید، محتوای آنها را خلاصه کنید، آدرس ایمیل «[NAME]» را پیدا کنید و یک پیش‌نویس جیمیل برای آنها به همراه خلاصه ایجاد کنید.»

ابزارهای بیشتر را کاوش کنید

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

۷. تمیز کردن

برای پاکسازی پروژه بدون حذف آن، می‌توانید APIها و سرویس‌های MCP که فعال کرده‌اید را غیرفعال کنید:

1. در کنسول گوگل کلود، به داشبورد API & Services بروید.
2. روی هر یک از APIهای Google Workspace و MCP که فعال کرده‌اید (مثلاً Calendar MCP، Chat MCP) کلیک کنید و روی Disable API کلیک کنید.

اگر دیگر قصد استفاده از آنها را ندارید، اعتبارنامه‌های کلاینت OAuth را در کنسول Google Auth Platform حذف کنید.

۸. تبریک

تبریک! شما با موفقیت سرورهای رسمی Google Workspace MCP را با استفاده از Gemini CLI پیکربندی و آزمایش کردید.

آنچه آموخته‌اید

• نحوه فعال کردن سرویس‌های MCP گوگل ورک‌اسپیس در گوگل کلود.
• نحوه پیکربندی کلاینت OAuth برای MCP.
• نحوه استفاده از رابط خط فرمان Gemini برای تعامل با داده‌های Google Workspace با استفاده از ابزارهای استاندارد.

اسناد مرجع

• مقدمه‌ای بر پروتکل زمینه مدل (MCP)
• پیکربندی سرورهای MCP گوگل ورک اسپیس
• پیکربندی موافقت‌نامه‌ی OAuth