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

بروتوكول سياق النموذج (MCP) هو معيار مفتوح يتيح للنماذج اللغوية الكبيرة التفاعل بأمان مع البيانات والتطبيقات الخارجية. يوفّر خادم MCP في "إعلانات Google" جسرًا موحّدًا إلى 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 Cloud:

التهيئة

لدمج الخادم في مضيف متوافق مع 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 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. الانتقال إلى دليل المشروع:

    cd <full path>/google-ads-mcp

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

    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_MCP_OAUTH_CLIENT_ID: معرّف عميل OAuth الذي تريد أن يستخدمه خادم MCP.
  • استبدِل GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET بسِر عميل OAuth الذي تريد أن يستخدمه خادم MCP.
  • GOOGLE_ADS_MCP_BASE_URL: عنوان URL الأساسي الذي يمكن الوصول إلى خادم MCP من خلاله: سيتم تعيين هذا العنوان تلقائيًا من خلال Google Cloud Run بعد عملية النشر الأولى. يمكنك تعديل متغيرات البيئة بعد النشر.
  • FASTMCP_HOST: اضبط هذا الخيار على 0.0.0.0 للسماح لـ FastMCP بقبول الاتصالات من جميع عناوين IP.
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_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