بدء استخدام Google Workspace MCP وGemini CLI

1- مقدمة

ملاحظة: هل تستخدم Antigravity؟ انتقِل إلى هذا الدرس التطبيقي حول الترميز بدلاً من ذلك. هذا الدليل خاص بأداة Gemini CLI.

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية استخدام بروتوكول سياق النموذج (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 مثبَّت على جهازك المحلي

يستغرق إكمال هذا الدرس التطبيقي حول الترميز 30 دقيقة تقريبًا.

الوصول بسهولة إلى هذا الدرس التطبيقي حول الترميز

2. قبل البدء

برنامج الاستخدام المبكر للمطوّرين في Google Workspace: يندرج الوصول إلى خوادم Google Workspace MCP ضمن برنامج الاستخدام المبكر العلني للمطوّرين. إذا لم يسبق لك الاشتراك، يُرجى التسجيل والتأكّد من قبول حسابك في البرنامج على https://developers.google.com/workspace/preview.

إنشاء مشروع على السحابة الإلكترونية أو اختياره

في Google Cloud Console، اختَر مشروعًا على Google Cloud أو أنشِئ مشروعًا.

تفعيل واجهات برمجة التطبيقات

لاستخدام خوادم Google Workspace MCP، عليك تفعيل واجهات برمجة التطبيقات في Google Workspace. في حين أنّ بعض خوادم MCP تعمل بشكل مستقل، لا يزال بعضها الآخر يتطلّب تفعيل واجهة برمجة التطبيقات العادية الأساسية:

• لا يزال Gmail وChat يتطلّبان واجهات برمجة التطبيقات العادية.
• يتطلّب Drive واجهة برمجة التطبيقات العادية لبعض الأدوات.
• لا يتطلّب تقويم Google تفعيل واجهة برمجة التطبيقات العادية.
• تتعامل ‫People API مع كل من إذن الوصول العادي ووظائف MCP، لذا ليس لديها خدمة MCP منفصلة لتفعيلها.

تفعيل واجهات برمجة التطبيقات

تفعيل خدمات MCP

بعد ذلك، فعِّل خدمات MCP المخصّصة للمنتجات.

تفعيل خدمات MCP

ضبط تطبيق Chat

لاستخدام خادم Google Chat MCP، عليك ضبط تطبيق Chat في مشروعك على Google Cloud.

1. في Google Cloud Console، ابحث عن Google Chat API وانقر على Google Chat API > إدارة > الإعدادات.انتقِل إلى Google Chat API
2. إعداد تطبيق Chat:
   • في حقل اسم التطبيق ، أدخِل Chat MCP.
   • في حقل عنوان URL للصورة الرمزية ، أدخِل https://developers.google.com/chat/images/quickstart-app-avatar.png.
   • في حقل الوصف ، أدخِل Chat MCP server.
   • ضمن الوظائف ، أوقِف تفعيل الميزات التفاعلية.
   • ضمن السجلات، اختَر تسجيل الأخطاء في Logging.
3. انقر على حفظ.

3. ضبط موافقة OAuth والعميل

تستخدم خوادم Google Workspace MCP بروتوكول OAuth 2.0 للمصادقة الآمنة. عليك ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth وإنشاء عميل لتطبيق على سطح المكتب.

إعداد شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth

تستخدم خوادم Google Workspace MCP بروتوكول OAuth 2.0 للمصادقة. عليك ضبط شاشة طلب الموافقة أولاً.

1. في Google Cloud Console، انتقِل إلى منصة Google للمصادقة > العلامة التجارية. انقر على البدء إذا لم يتم ضبطها.
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

1. انتقِل إلى منصة Google للمصادقة > العملاء > إنشاء عميل.
2. اختَر تطبيق على سطح المكتب كنوع التطبيق.
3. أطلِق عليه اسم Gemini CLI.
4. انقر على إنشاء وانسخ معرّف العميل وسر العميل. ستحتاج إليهما في الخطوة التالية.

4. ضبط 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"
        ]
      }
    }
  }
}

5. مصادقة خوادم MCP والتحقّق منها

قبل أن تتمكّن من استخدام خوادم MCP، عليك مصادقتها والتحقّق من أنّها متصلة.

بدء استخدام Gemini CLI

شغِّل الأمر التالي في الوحدة الطرفية لبدء Gemini CLI:

gemini

مصادقة

صادِق على الخدمات التي تريد اختبارها من خلال تشغيل الأمر المقابل في Gemini CLI. عليك المصادقة على الخدمات التي تخطط لاستخدامها في هذا الدرس التطبيقي حول الترميز فقط.

التقويم

/mcp auth calendar

محادثة

/mcp auth chat

Drive

/mcp auth drive

Gmail

/mcp auth gmail

الأشخاص

/mcp auth people

اتّبِع التعليمات في المتصفّح لمنح الإذن لكل خدمة.

تأكيد الاتصال

تأكَّد من تحميل الأدوات وجاهزيتها:

/mcp list

من المفترض أن يظهر لك ناتج يشير إلى أنّ الخدمات Ready مع إدراج أدواتها.

6. اختبار خوادم MCP

يمكنك الآن التفاعل مع بيانات Google Workspace باستخدام اللغة الطبيعية. في ما يلي بعض الطلبات النموذجية لكل خدمة.

ملاحظة: استبدِل العناصر النائبة بين أقواس مربّعة في الطلبات أدناه (مثل [NAME] و[FILE_NAME]) بقيم فعلية من بيانات Google Workspace الخاصة بك.

تقويم Google

يمكنك أن تطلب من Gemini معلومات عن جدولك الزمني:

• "ما هي اجتماعاتي القادمة هذا الأسبوع؟"
• "هل لديّ أي وقت فراغ غدًا بعد الظهر؟"

Google Chat

يمكنك أن تطلب من Gemini البحث عن الرسائل:

• "ابحث عن الرسائل التي تحتوي على "[KEYWORD]" في "[SPACE_NAME]""

Google Drive

يمكنك أن تطلب من Gemini العثور على الملفات أو قراءتها:

• "ابحث عن الملفات على Google Drive التي تحتوي على "[KEYWORD]""
• "أدرِج أحدث المستندات التي عدّلتها."
• "اقرأ محتوى مستند "[FILE_NAME]" ولخِّص الأهداف الرئيسية."

Gmail

يمكنك أن تطلب من Gemini البحث عن رسائلك الإلكترونية أو إدارتها:

• "لخِّص آخر 5 رسائل إلكترونية تلقّيتها."
• "أنشِئ مسودة رسالة إلكترونية إلى "[EMAIL_ADDRESS]" تطلب فيها آخر الأخبار عن مشروع "[PROJECT_NAME]"."

‫People API

يمكنك أن تطلب من Gemini معلومات عن ملفك الشخصي أو جهات اتصالك:

• "ما هو اسمي وفقًا لملفي الشخصي في حساب Google؟"
• "ابحث عن معلومات الاتصال الخاصة بـ "[NAME]"."

الجمع بين خدمات متعددة

تظهر الإمكانات الحقيقية لبروتوكول MCP عندما ينسّق Gemini المهام على مستوى خدمات متعددة. جرِّب هذه الطلبات التي توضّح الإمكانات المتعدّدة الخدمات:

• "ابحث عن الملفات في Drive ذات الصلة بـ "آخر الأخبار عن [PROJECT_NAME]"، ولخِّص محتواها، وابحث عن عنوان البريد الإلكتروني لـ "[NAME]"، وأنشِئ مسودة رسالة إلكترونية في Gmail إليه تتضمّن الملخّص."

استكشاف المزيد من الأدوات

هذه مجرد أمثلة قليلة على ما يمكنك فعله. للاطّلاع على القائمة الكاملة بالأدوات المتاحة لكل خدمة وتجربتها، يُرجى الرجوع إلى قسم المنتجات المتوافقة في المستندات الرسمية.

7- تَنظيم

لتنظيف مشروعك بدون حذفه، يمكنك إيقاف واجهات برمجة التطبيقات وخدمات MCP التي فعّلتها:

1. في Google Cloud Console، انتقِل إلى لوحة بيانات واجهات برمجة التطبيقات والخدمات.
2. انقر على كل من واجهات برمجة التطبيقات في Google Workspace وMCP التي فعّلتها (مثل Calendar MCP وChat MCP) وانقر على إيقاف واجهة برمجة التطبيقات.

احذف بيانات اعتماد عميل OAuth في وحدة تحكّم منصة Google للمصادقة إذا لم تعُد تخطط لاستخدامها.

8- تهانينا

تهانينا! لقد نجحت في ضبط خوادم Google Workspace MCP الرسمية واختبارها باستخدام Gemini CLI.

ما تعلّمته

• كيفية تفعيل خدمات Google Workspace MCP في Google Cloud
• كيفية ضبط عميل OAuth لبروتوكول MCP
• كيفية استخدام Gemini CLI للتفاعل مع بيانات Google Workspace باستخدام الأدوات العادية

مستندات مرجعية

• مقدمة عن بروتوكول سياق النموذج (MCP)
• ضبط خوادم Google Workspace MCP
• ضبط موافقة OAuth