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

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

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

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

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

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

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

طريقة عمل حلقة التفاعل

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

البدء

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

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

قبل الضبط، تأكَّد من توفّر بيانات الاعتماد التالية من وحدة تحكّم Google Cloud:

التهيئة

لدمج الخادم في مضيف متوافق مع MCP، أضِف الإدخال التالي إلى ملف إعداد MCP الخاص بالمضيف، مثل settings.json، وأشِر إلى GOOGLE_APPLICATION_CREDENTIALS في ملف JSON الخاص بـ ADC (أو اضبط ADC التلقائي باستخدام gcloud auth application-default login). إذا كنت تصل إلى الحسابات من خلال حساب إداري، يمكنك أيضًا ضبط GOOGLE_ADS_LOGIN_CUSTOMER_ID. راجِع مستندات المضيف لمعرفة الموقع واسم الملف المحدّدَين لهذا الإعداد.

{
  "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_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
      }
    }
  }
}

النشر على 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، مثل "campaign".

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

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

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

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