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

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

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

• مستودع GitHub: يمكنك العثور على العروض التوضيحية والأمثلة والإبلاغ عن الأخطاء أو اقتراح ميزات في مستودع google-ads-mcp.

  استخدِم علامة التبويب "المشاكل" للإبلاغ عن الأخطاء وطلب الميزات.

• المنتدى: انضمّ إلى قناة #ads-api-ai-tools على Google Advertising Community Discord.

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

من خلال تنفيذ خادم 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:

• رقم تعريف المشروع: رقم تعريف مشروعك على Google Cloud راجِع صفحة نظرة عامة على Google Ads API للتأكّد من أنّ مشروعك يتضمّن مستويات الوصول "الوصول إلى المستكشف" أو "الوصول الأساسي" أو "الوصول العادي". إذا لم يكن الأمر كذلك، قدِّم طلبًا للحصول على أحد مستويات الوصول هذه
• بيانات اعتماد OAuth: إما زوج من معرّف عميل OAuth 2.0 وسر العميل، أو مجموعة من بيانات الاعتماد التلقائية للتطبيق.

التهيئة

لدمج الخادم في مضيف متوافق مع 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 Ads (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