خادم MCP في "إعلانات Google": دليل الدمج للمطوّرين

بروتوكول سياق النموذج (MCP) هو معيار مفتوح يتيح للنماذج اللغوية الكبيرة التفاعل بأمان مع البيانات والتطبيقات الخارجية. يوفّر خادم بروتوكول سياق النموذج المُدار (MCP) من Google Ads جسرًا موحّدًا إلى Google Ads API، ما يتيح لوكلاء الذكاء الاصطناعي تحليل بيانات الحملات واستردادها باستخدام اللغة الطبيعية.

المراجع والدعم من المنتدى

نظرة عامة فنية

من خلال تنفيذ خادم MCP هذا، لن تحتاج إلى كتابة "رمز ربط" مخصّص للمصادقة على Google Ads API، واسترداد الموارد، وتحليل البيانات. يعرض الخادم أدوات معيّنة يمكن أن يكتشفها نموذج لغوي كبير ويستخدمها بشكل مستقل.

المواصفات الرئيسية

  • البروتوكول: MCP (بروتوكول سياق النموذج)
  • الوضع: للقراءة فقط (الإصدار الحالي)
  • اللغة: Python
  • النقل: الإدخال/الإخراج العادي (stdio)
  • المصادقة: OAuth 2.0 أو حساب الخدمة

كيف تعمل حلقة التفاعل؟

  1. الطلب: يرسل المستخدم طلب بحث مثل "كيف كان أداء حملتي هذا الأسبوع؟".
  2. الاستكشاف: يفحص النموذج اللغوي الكبير الأدوات المتاحة له ويحدّد google-ads-mcp إمكانات البحث.
  3. التنفيذ: ينفِّذ خادم MCP منطق Python الأساسي للاستعلام عن Google Ads API.
  4. إدخال السياق: يتم عرض النتائج المنظَّمة في نافذة سياق النموذج اللغوي الكبير.
  5. الردّ: يجمع النموذج اللغوي الكبير البيانات في ردّ يمكن للمستخدمين العاديين قراءته.

البدء

اتّبِع الخطوات التالية لإعداد خادم MCP في "إعلانات Google" واستخدامه.

المتطلبات الأساسية

قبل إجراء عملية الإعداد، تأكَّد من توفّر بيانات الاعتماد التالية من وحدة تحكّم المطوّرين في "إعلانات Google":

  • الرمز المميز للمطوِّر: هو سلسلة الدخول الفريدة المكوّنة من 22 حرفًا.
  • رقم تعريف المشروع: رقم تعريف مشروعك على Google Cloud.
  • بيانات اعتماد OAuth: إما زوج من معرّف العميل/سر العميل في OAuth2، أو مجموعة من بيانات الاعتماد التلقائية للتطبيق.

التهيئة

لدمج الخادم في مضيف متوافق مع MCP، أضِف الإدخال التالي إلى ملف إعدادات MCP الخاص بالمضيف، مثل settings.json. راجِع مستندات المضيف لمعرفة الموقع الجغرافي واسم الملف الدقيقَين لهذا الإعداد.

JSON

{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleads/google-ads-mcp.git",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
      }
    }
  }
}

النشر على Google Cloud

بدلاً من استضافة خادم MCP هذا محليًا، يمكنك استضافته على Google Cloud Run أو على أي بنية أساسية أخرى مستندة إلى السحابة الإلكترونية. ويكون هذا مفيدًا في حال أردت مشاركة الخادم بين وكلاء مختلفين أو تشغيله كخدمة ويب.

المتطلبات الأساسية

  1. مشروع Google Cloud

  2. تم تثبيت أداة سطر الأوامر gcloud، وتمت المصادقة عليها، وتم ضبط مشروع نشط:

    gcloud config set project YOUR_PROJECT_ID

إنشاء صورة Docker ونشرها

يمكنك استخدام Cloud Build لإنشاء الصورة ونقلها إلى Artifact Registry بدون الحاجة إلى تثبيت Docker على جهازك.

  1. إنشاء مستودع في Artifact Registry:

    gcloud artifacts repositories create mcp-servers --repository-format=docker --location=us-central1

  2. إنشاء الصورة وإرسالها:

    gcloud builds submit --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest .

    يُرجى العِلم أنّه يجب تنفيذ هذه الخطوة كلّما أردت تحديث الخادم الذي تم نشره إلى أحدث إصدار.

النشر على Google Cloud Run

احرص على ضبط متغيّرات البيئة المطلوبة:

  • GOOGLE_PROJECT_ID: رقم تعريف مشروعك على Google Cloud
  • استبدِل GOOGLE_ADS_DEVELOPER_TOKEN برمز المطوّر الذي تريد أن يستخدمه خادم MCP.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: معرّف عميل OAuth الذي تريد أن يستخدمه خادم MCP.
  • استبدِل GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET بسِر عميل OAuth الذي تريد أن يستخدمه خادم MCP.
  • GOOGLE_ADS_MCP_BASE_URL: عنوان URL الأساسي الذي يمكن الوصول إلى خادم MCP من خلاله: سيتم تعيين هذا العنوان تلقائيًا من خلال Google Cloud Run بعد عملية النشر الأولى. يمكنك تعديل متغيرات البيئة بعد النشر.
  • استخدِم القيمة 0.0.0.0 للسماح لـ FastMCP بقبول الاتصالات من جميع عناوين IP.FASTMCP_HOST
gcloud run deploy google-ads-mcp \
  --image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_PROJECT_ID=YOUR_PROJECT_ID,GOOGLE_ADS_DEVELOPER_TOKEN=YOUR_DEVELOPER_TOKEN,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,GOOGLE_ADS_MCP_BASE_URL=YOUR_BASE_URL,FASTMCP_HOST=0.0.0.0"

ضبط إعدادات برنامج MCP

بعد النشر، عدِّل إعدادات برنامج MCP (على سبيل المثال، ~/.gemini/settings.json) لاستخدام عنوان URL الخاص بـ Cloud Run.

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://your-cloud-run-url.a.run.app/mcp"
    }
  }
}

الإمكانات الأساسية (الأدوات)

يعرض الخادم أدوات مصمّمة لاكتشاف الحسابات وإعداد تقارير الأداء:

  • ‫list_accessible_customers: تعرض هذه السمة قائمة بأرقام تعريف عملاء "إعلانات Google" وأسماء الحسابات التي يمكن للمستخدم الذي تمّت مصادقته الوصول إليها.
  • search: تنفّذ طلبات لغة طلبات البحث في "إعلانات Google" (GAQL) لجلب مقاييس الموارد والميزانيات والحالة.

  • ‫get_resource_metadata: تسترد هذه السمة البيانات الوصفية الخاصة بنوع أحد موارد Google Ads API، مثل "الحملة".

    ويفيد ذلك في فهم بنية البيانات والحقول المتاحة للاستعلام.

نماذج طلبات للبدء

الاستفسار عن الإجراءات التي يمكن للخادم تنفيذها:

What can the google-ads-mcp server do?

السؤال عن العملاء:

What customers do I have access to?

طرح أسئلة حول الحملات:

How many active campaigns do I have?
How is my campaign performance this week?
Give me a report of the top spending campaigns split by device category over the
last 7 days for account 1234567890