شروع به کار با Google Workspace MCP و Gemini CLI

۱. مقدمه

توجه: آیا هنوز از Gemini CLI استفاده می‌کنید؟ برای آشنایی با راه‌اندازی سرورهای Google Workspace MCP با Antigravity CLI، به این codelab بروید. اطلاعات بیشتر درباره این انتقال را می‌توانید در این پست وبلاگ رسمی پیدا کنید.

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

آنچه انجام خواهید داد

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

آنچه نیاز خواهید داشت

• مرورگر وب مانند Chrome
• پروژه Google Cloud
• حساب Google Workspace
• ‫Gemini CLI در ماشین محلی‌تان نصب شده باشد

تکمیل این codelab تقریباً ۳۰ دقیقه طول می‌کشد.

دسترسی آسان به این codelab

۲. قبل‌از شروع

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

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

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

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

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

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

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

فعال کردن «خدمات MCP»

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

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

پیکربندی برنامه Chat

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

1. در کنسول Google Cloud، Google Chat API را جستجو کنید و روی Google Chat API > مدیریت > پیکربندی کلیک کنید.رفتن به Google Chat API
2. برنامه Chat را راه‌اندازی کنید:
   • در فیلد نام برنامه، Chat MCP را وارد کنید.
   • در فیلد نشانی وب چهرک، https://developers.google.com/chat/images/quickstart-app-avatar.png را وارد کنید.
   • در شرح، Chat MCP server را وارد کنید.
   • در بخش عملکرد، فعال کردن ویژگی‌های تعاملی را خاموش کنید.
   • در بخش گزارش‌ها، گزارش کردن خطاها در Logging را انتخاب کنید.
3. روی ذخیره کلیک کنید.

۳. پیکربندی «رضایت OAuth» و «کارخواه»

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

راه‌اندازی صفحه کسب رضایت OAuth

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

1. در کنسول Google Cloud، به پلاتفرم Google Auth > نمانام‌سازی بروید. اگر پیکربندی نشده است، روی شروع به کار کلیک کنید.
2. پیکربندی اطلاعات برنامه:
   • نام برنامه: Google Workspace MCP Servers
   • ایمیل پشتیبانی کاربر: ایمیلتان را انتخاب کنید.
3. مخاطب را پیکربندی کنید: داخلی را انتخاب کنید (یا اگر «داخلی» دردسترس نیست، خارجی را انتخاب کنید).
4. اطلاعات تماس را پیکربندی کنید: نشانی ایمیلتان را وارد کنید.
5. «خط‌مشی داده‌های کاربر» را مرور کنید و با آن موافقت کنید، سپس روی ایجاد کلیک کنید.
6. اگر خارجی را انتخاب کرده‌اید، به مخاطب بروید و ایمیلتان را در بخش کاربران آزمایشی اضافه کنید.
7. به دسترسی به داده > افزودن یا برداشتن دامنه‌ها بروید. در بخش افزودن دستی دامنه‌ها، موارد زیر را برای سرورهایی که می‌خواهید استفاده کنید اضافه کنید:
   • تقویم Google: https://www.googleapis.com/auth/calendar.calendarlist.readonly، https://www.googleapis.com/auth/calendar.events.freebusy، https://www.googleapis.com/auth/calendar.events.readonly
   • Google Chat: 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
   • Google Drive: https://www.googleapis.com/auth/drive.readonly، https://www.googleapis.com/auth/drive.file
   • Gmail: https://www.googleapis.com/auth/gmail.readonly، https://www.googleapis.com/auth/gmail.compose
   • People API: https://www.googleapis.com/auth/directory.readonly، https://www.googleapis.com/auth/userinfo.profile، https://www.googleapis.com/auth/contacts.readonly
8. روی افزودن به جدول، سپس به‌روزرسانی، و درنهایت ذخیره کلیک کنید.

ایجاد شناسه کارخواه OAuth

هنگام پیکربندی کارخواه OAuth 2.0 برای سرورهای MCP در Google Workspace، باید تنظیم طبقه‌بندی عاملی (is_agentic) را با انتخاب استفاده از این کارخواه برای عامل مجهز به هوش مصنوعی فعال کنید. کارخواه‌های OAuth که این تنظیم را فعال نکرده باشند نمی‌توانند نقاط پایانی MCP در Google Workspace را فراخوانی کنند.

1. به پلاتفرم Google Auth > کارخواه‌ها > ایجاد کارخواه (یا میاناهای برنامه‌سازی کاربردی و سرویس‌ها > اعتبارنامه‌ها > ایجاد اعتبارنامه‌ها > شناسه کارخواه OAuth) بروید.
2. برنامه رایانه‌ای را به‌عنوان نوع برنامه انتخاب کنید.
3. نام آن را Gemini CLI بگذارید.
4. استفاده از این کارخواه برای عامل مجهز به هوش مصنوعی را انتخاب کنید تا پرچم طبقه‌بندی is_agentic در کارخواه OAuth فعال شود.
5. روی ایجاد کلیک کنید و شناسه کارخواه و رمز کارخواه را کپی کنید. در مرحله بعد به این موارد نیاز خواهید داشت.

۴. پیکربندی کردن Gemini CLI

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

محیط محلی لازم است: برای این مرحله از Cloud Shell استفاده نکنید. ‫Gemini CLI برای اصالت‌سنجی 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 CLI

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

gemini

اصالت‌سنجی

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

تقویم

/mcp auth calendar

گپ

/mcp auth chat

Drive

/mcp auth drive

Gmail

/mcp auth gmail

افراد

/mcp auth people

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

تأیید اتصال

تأیید کنید که ابزارها بار شده و آماده‌اند:

/mcp list

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

‫۶. آزمایش سرورهای MCP

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

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

تقویم Google

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

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

Google Chat

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

• «Look for messages containing ‘[KEYWORD]' in ‘[SPACE_NAME]'» (پیام‌های حاوی «[KEYWORD]» را در «[SPACE_NAME]» پیدا کن)

Google Drive

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

• «Search for files on my Google Drive that contain ‘[KEYWORD]'.‎» (فایل‌هایی را در Google Drive من جستجو کن که حاوی «[کلیدواژه]» باشند.)
• «جدیدترین اسنادی را که ویرایش کردم فهرست کن.»
• «محتوای سند «[FILE_NAME]» من را بخوان و اهداف اصلی را خلاصه کن.»

Gmail

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

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

People API

درباره نمایه یا مخاطبینتان از Gemini بپرسید:

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

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

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

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

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

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

‫۷. مرتب‌سازی

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

1. در «کنسول Google Cloud»، به داشبورد API و سرویس‌ها بروید.
2. روی هریک از میاناهای برنامه‌سازی کاربردی Google Workspace و MCP که فعال کرده‌اید (برای مثال، Calendar MCP،‏ Chat MCP) کلیک کنید و روی غیرفعال کردن میانای برنامه‌سازی کاربردی کلیک کنید.

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

‫۸. تبریک می‌گوییم

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

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

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

اسناد مرجع

• مقدمه‌ای بر «پروتکل بافتار مدل» (MCP)
• پیکربندی سرورهای Google Workspace MCP
• پیکربندی رضایت OAuth