خادم 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) أو HTTP القابل للبث (streamable-http / Cloud Run)
  • المصادقة: بروتوكول OAuth 2.0 أو حساب الخدمة

آلية عمل حلقة التفاعل

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

البدء

اتّبِع الخطوات التالية لضبط خادم بروتوكول سياق النموذج (MCP) في "إعلانات Google" واستخدامه.

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

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

التهيئة

لدمج الخادم في مضيف متوافق مع بروتوكول سياق النموذج (MCP)، أضِف الإدخال التالي إلى ملف إعداد بروتوكول سياق النموذج (MCP) الخاص بالمضيف، مثل settings.json، واضبط GOOGLE_APPLICATION_CREDENTIALS على ملف JSON لبيانات الاعتماد التلقائية للتطبيق (أو اضبط بيانات الاعتماد التلقائية للتطبيق التلقائية باستخدام 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 2.0 (تم ضبطه على أنّه تطبيق ويب في مشروع Google Cloud) لمصادقة OAuth على مستوى التطبيق. يجب التأكد ممّا يلي:
    • لقد أضفت معرّفات الموارد المنتظمة (URI) المناسبة لإعادة التوجيه المفوّضة لأي عملاء ذكاء اصطناعي تخطّط للربط بهم (مثل https://claude.ai/api/mcp/auth_callback أو https://chatgpt.com/connector_platform_oauth_redirect أو https://antigravity.google/oauth-callback).
    • لقد أضفت النطاق https://www.googleapis.com/auth/adwords إلى شاشة طلب موافقة OAuth ضمن واجهات برمجة التطبيقات والخدمات > شاشة طلب موافقة OAuth > الوصول إلى البيانات (إضافة نطاقات أو إزالتها).
    • إذا تم ضبط حالة نشر شاشة طلب موافقة OAuth على الاختبار (الإعداد التلقائي)، لقد أضفت حسابات Google التي تتصل بخادم بروتوكول سياق النموذج (MCP) على أنّها مستخدمون تجريبيون ضمن واجهات برمجة التطبيقات والخدمات > شاشة طلب موافقة OAuth > الجمهور (مستخدمون تجريبيون > ‎+ إضافة مستخدمين).
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: سر عميل OAuth المقابل لمعرّف عميل OAuth.
  • GOOGLE_ADS_MCP_BASE_URL: الجزء الأساسي من عنوان URL العلني الذي يمكن الوصول إليه من خادم بروتوكول سياق النموذج (MCP) (على سبيل المثال، https://google-ads-mcp-xyz-uc.a.run.app). بما أنّ Google Cloud Run ينشئ عنوان URL هذا أثناء عملية النشر الأولية، يمكنك التفعيل بدون هذا المتغيّر أولاً، ثم تعديل الخدمة بعد التفعيل.
  • FASTMCP_HOST: اضبط هذا الخيار على 0.0.0.0 للسماح لـ FastMCP بقبول الاتصالات من جميع عناوين IP.

انشر الخدمة على Google Cloud Run:

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,FASTMCP_HOST=0.0.0.0"

بعد أن يكمل Cloud Run عملية النشر، استرجِع عنوان URL للخدمة الذي تم تعيينه وعدِّل الخدمة باستخدام متغيّر البيئة GOOGLE_ADS_MCP_BASE_URL:

gcloud run services update google-ads-mcp \
  --region us-central1 \
  --update-env-vars="GOOGLE_ADS_MCP_BASE_URL=https://your-cloud-run-url.a.run.app"

نموذج المصادقة والأمان

يؤدي النشر باستخدام العلامة --allow-unauthenticated إلى إيقاف عملية التحقّق من إدارة الهوية وإمكانية الوصول (IAM) على مستوى البنية التحتية في Cloud Run (roles/run.invoker) حتى يتمكّن عملاء الذكاء الاصطناعي الخارجيون من الاتصال بدون الحاجة إلى رموز حسابات الخدمة على Google Cloud. بدلاً من ذلك، يتم تفويض المصادقة إلى طبقة التطبيق:

  • عند تقديم GOOGLE_ADS_MCP_OAUTH_CLIENT_ID وGOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET، يفرض خادم بروتوكول سياق النموذج (MCP) بروتوكول Google OAuth 2.0 على جميع الطلبات الواردة، ويطلب من المتصلين غير المصادَق عليهم الردّ برمز HTTP 401. يتم تنفيذ جميع طلبات الأدوات بشكلٍ صارم ضمن هوية OAuth للمتصل المصادَق عليه.
  • يؤدي حذف العلامة --allow-unauthenticated إلى فرض إدارة الهوية وإمكانية الوصول (IAM) على مستوى البنية التحتية في Cloud Run، ما يتطلّب من المتصلين تمرير رموز الهوية OIDC من Google Cloud مع كل طلب. بما أنّ عملاء الذكاء الاصطناعي العاديين (مثل Claude وChatGPT) يُصادقون باستخدام OAuth للمستخدم النهائي بدلاً من رموز الهوية في Google Cloud IAM، تتطلّب الاتصالات المباشرة من هذه المنصات استخدام العلامة --allow-unauthenticated مع OAuth على مستوى التطبيق.

ضبط عميل بروتوكول سياق النموذج (MCP)

بعد النشر، اضبط عميل بروتوكول سياق النموذج (MCP) باستخدام عنوان URL الخاص بـ Cloud Run. بما أنّ الخادم يتطلّب مصادقة OAuth 2.0، يجب أن يتيح العميل تدفق OAuth لبروتوكول سياق النموذج (MCP) أو أن يقدّم رمزًا حاملًا مميزًا مُفوّضًا:

  • العملاء الذين يتيحون بروتوكول OAuth: بالنسبة إلى العملاء الذين يتيحون اكتشاف OAuth لبروتوكول سياق النموذج (MCP) (مثل Antigravity)، يؤدي الاتصال بنقطة النهاية إلى ظهور إشعار للمصادقة لتسجيل الدخول باستخدام حساب Google ومنح النطاق https://www.googleapis.com/auth/adwords (المدرَج على أنّه .../auth/adwords في Google Cloud Console).
  • منصات الذكاء الاصطناعي الخارجية (Claude وChatGPT): في إعدادات الموصِّل أو التكامل الخاصة بعميلك، أضِف موصِّلاً مخصّصًا يشير إلى عنوان URL الخاص بـ Cloud Run باستخدام المسار /mcp (على سبيل المثال، https://your-cloud-run-url.a.run.app/mcp)، واختَر مصادقة OAuth 2.0 (باستخدام معرّف عميل OAuth وسر العميل الخاصَين بك)، وتأكَّد من إضافة معرّف الموارد المنتظم (URI) لردّ الاتصال الخاص بالعميل إلى معرّفات الموارد المنتظمة (URI) المفوّضة لإعادة التوجيه الخاصة بعميل OAuth. (يمكن للمشاركين المدرَجين في القائمة المسموح بها في الإصدار التجريبي لنقطة النهاية المستضافة الرجوع أيضًا إلى دليل إعداد بروتوكول سياق النموذج (MCP) المستضاف.)
  • العملاء الذين لا يتيحون بروتوكول OAuth: سيتلقّى العملاء الذين لا يتيحون تدفقات HTTP OAuth ردًّا غير مسموح به برمز HTTP 401. بالنسبة إلى هذه الأدوات، استخدم إعدادات `stdio` المحلية بدلاً من ذلك.

مثال على الإعدادات لعميل يتيح بروتوكول OAuth (على سبيل المثال، ~/.gemini/settings.json):

{
  "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