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

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

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

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

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

التهيئة

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

اختياري: تزويد الوكيل بالمهارات و"مساعد المطوّر"

يمنح خادم MCP في "إعلانات Google" عميل الذكاء الاصطناعي إذنًا بالقراءة فقط للوصول إلى بيانات الحساب المباشرة. لمساعدة وكيلك في إنشاء طلبات بحث صالحة باستخدام لغة طلب البحث في "إعلانات Google" (GAQL)، وتشخيص التغييرات في أداء الحساب، وإنشاء رمز مكتبة العميل، يمكنك ربط خادم MCP بهذه الأدوات المرافقة:

  • مهارات وكيل Google Ads API: وحدات محمولة من التعليمات وسير العمل الخاصة بـ Google Ads API، بما في ذلك google-ads-api-mcp-setup وgoogle-ads-api-account-diagnostics وgoogle-ads-api-quickstart، والتي تعلّم وكيلك كيفية استخدام خادم MCP في "إعلانات Google" بفعالية مع تقليل النفقات العامة للرموز المميّزة. يمكنك تثبيتها باستخدام أمر واحد (يتطلّب ذلك Node.js)، أو الاطّلاع على دليل مهارات وكيل Google Ads API لخيارات Antigravity وClaude Code وCodex وCursor:

    npx skills add google/skills/skills/ads

  • ‫Google Ads API Developer Assistant: مكوّن إضافي معياري لـ Google Antigravity وClaude Code يوفّر فحصًا محليًا لمخطط Protobuf، والتحقّق الآلي من صحة GAQL، وإنشاء رمز مكتبة البرامج (بما في ذلك النصوص البرمجية للتعديل)، وتحديد المشاكل وحلّها في الإحالات الناجحة غير الإلكترونية. يمكنك التعرّف على طريقة عمله في مقالة ما هو Google Ads API Developer Assistant؟ أو اتّباع دليل التثبيت.

النشر على 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 إلى إيقاف عملية التحقّق من "إدارة الهوية وإمكانية الوصول" (roles/run.invoker) على مستوى البنية الأساسية في Cloud Run، ما يتيح لعملاء الذكاء الاصطناعي الخارجيين الاتصال بدون الحاجة إلى رموز مميّزة لحسابات الخدمة في 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 الخاص بالمستخدم النهائي للمصادقة بدلاً من رموز تعريف Cloud IAM في Google Cloud، تتطلّب الاتصالات المباشرة من هذه المنصات استخدام --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: ينفّذ طلبات 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

الخطوات التالية