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

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

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

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

  استخدِم علامة التبويب "المشاكل" (Issues) لإرسال تقارير الأخطاء وطلبات الميزات.

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

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

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

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

• البروتوكول: بروتوكول سياق النموذج (MCP)
• الوضع: القراءة والتغيير الجزئي (إنشاء مواد العرض وتحميل الفيديوهات وإدارة التصنيفات من خلال التحقّق من الاقتراح والتأكيد أو وضع القراءة فقط القابل للضبط)
• اللغة: Python 3.10 أو إصدار أحدث
• النقل: الإدخال/الإخراج المعياري (stdio) أو HTTP القابل للبث (streamable-http على Cloud Run)
• المصادقة: بيانات الاعتماد التلقائية للتطبيق (بيانات اعتماد مستخدم OAuth 2.0 أو حساب الخدمة) لـ stdio المحلي، أو بيانات اعتماد تطبيق الويب OAuth 2.0 لبروتوكول HTTP عن بُعد

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

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

البدء

اتّبِع الخطوات التالية لضبط خادم MCP في "إعلانات Google" وتشغيله على جهازك. لنشر خدمة عن بُعد مشتركة بدلاً من ذلك، يُرجى الاطّلاع على النشر على Google Cloud.

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

قبل ضبط الخادم، يجب إكمال المتطلبات الأساسية التالية في بيئتك المحلية ووحدة تحكّم Google Cloud:

• مشروع على Google Cloud: أنشِئ مشروعًا على Google Cloud أو اختَره مع تفعيل Google Ads API. يؤدي تفعيل واجهة برمجة التطبيقات إلى منح إذن وصول تجريبي لاختبار عمليات سير العمل الخاصة بالقراءة والتعديل في الحسابات التجريبية. للوصول إلى حسابات الإنتاج، يُرجى الاطّلاع على صفحة "نظرة عامة" في Google Ads API للحصول على إذن بالوصول الاستكشافي أو الأساسي أو العادي، أو تقديم طلب للحصول على أحد مستويات الوصول هذه. وإلا، ستتعذّر طلبات الإصدار العلني مع ظهور الخطأ AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION. ستوقف Google الرموز المميّزة للمطوّرين (GOOGLE_ADS_DEVELOPER_TOKEN) في 9 سبتمبر 2026. يحدّد مشروع Google Cloud الذي يملك عميل OAuth أو حساب الخدمة مستوى وصولك إلى واجهة برمجة التطبيقات.
• بيانات الاعتماد: تتم المصادقة في وضع stdio المحلي باستخدام بيانات الاعتماد التلقائية للتطبيق (ADC) من ملف JSON لسر عميل OAuth 2.0 أو حساب خدمة في مشروعك على السحابة الإلكترونية. اضبط متغيّر البيئة GOOGLE_CLOUD_PROJECT عند الحاجة لتحديد الحصة التلقائية أو مشروع "بيانات الاعتماد التلقائية للتطبيق". أما عمليات النشر عن بُعد في streamable-http، فتتطلّب معرِّف عميل وسر عميل لتطبيق ويب يستخدم بروتوكول OAuth 2.0 (يُرجى الاطّلاع على النشر في Google Cloud Run).
• البرامج المحلية (لوضع stdio): ثبِّت الإصدار 3.10 من Python أو إصدارًا أحدث وpipx وأداة سطر أوامر gcloud (المستخدَمة لإنشاء ملفات ADC للمستخدم).

التهيئة

1. أنشِئ بيانات الاعتماد التلقائية للتطبيق (ADC) باستخدام عميل OAuth من مشروعك على Google Cloud الذي تم تفعيل واجهة برمجة التطبيقات فيه، وأدرِج نطاق Google Ads API:

   gcloud auth application-default login \
     --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
     --client-id-file=PATH_TO_CLIENT_SECRET_JSON
   

   غيِّر القيم في السلسلة على الشكل التالي:

   • PATH_TO_CLIENT_SECRET_JSON: المسار إلى ملف JSON لسرّ عميل OAuth 2.0

   يعرض هذا الأمر Credentials saved to file: [PATH_TO_CREDENTIALS_JSON] (مثل ~/.config/gcloud/application_default_credentials.json على نظامَي التشغيل Linux وmacOS). للمصادقة باستخدام حساب خدمة بدلاً من ذلك، يمكنك تخطّي هذه الخطوة وتوجيه GOOGLE_APPLICATION_CREDENTIALS إلى ملف JSON لمفتاح حساب الخدمة، أو تمرير --impersonate-service-account إلى gcloud auth application-default login.

2. أضِف الخادم إلى ملف إعدادات MCP الخاص بالمضيف (مثل ~/.gemini/config/mcp_config.json أو ~/.gemini/settings.json أو ~/.claude/settings.json):

   {
     "mcpServers": {
       "google-ads-mcp": {
         "command": "pipx",
         "args": [
           "run",
           "--spec",
           "google-ads-mcp==0.0.6",
           "google-ads-mcp"
         ],
         "env": {
           "GOOGLE_CLOUD_PROJECT": "PROJECT_ID",
           "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON"
         }
       }
     }
   }
   

   غيِّر القيم في السلسلة على الشكل التالي:

   • ‫PROJECT_ID: رقم تعريف مشروعك على Google Cloud
   • ‫PATH_TO_CREDENTIALS_JSON: المسار إلى ملف JSON الخاص ببيانات الاعتماد التلقائية للتطبيق (ADC) الذي تم طباعته في الخطوة 1، أو إلى ملف JSON الخاص بمفتاح حساب الخدمة. يمكنك حذف GOOGLE_APPLICATION_CREDENTIALS عند استخدام الموقع الجغرافي التلقائي لملف gcloud ADC.

   للوصول إلى حسابات العملاء من خلال حساب إداري، اضبط GOOGLE_ADS_LOGIN_CUSTOMER_ID (10 أرقام، بدون واصلات) في env، أو مرِّر المَعلمة login_customer_id في طلبات الأدوات الفردية.

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

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

• مهارات وكيل 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؟ أو اتّباع دليل التثبيت.

الإمكانات الأساسية

توضّح الأقسام التالية أدوات القراءة وأدوات التعديل الجزئي والمراجع في الخادم. اعتبارًا من الإصدار v0.0.6، يتم تسجيل الأدوات تلقائيًا باستخدام بادئة مساحة الاسم الخاصة بفئتها (مثل search_search). عند ترقية الطلبات أو القوائم المسموح بها من الإصدارات التي لا تحتوي على بادئة، يجب تعديل أسماء الأدوات أو ضبط بادئة فارغة ("") في tools_config.yaml (يُرجى الاطّلاع على ضبط مساحات أسماء الأدوات ووضع القراءة فقط).

أدوات القراءة

• customers_list_accessible_customers (الأداة list_accessible_customers): تعرض هذه الأداة أرقام تعريف عملاء "إعلانات Google" التي يمكن للمستخدم الذي تمّت مصادقته الوصول إليها مباشرةً.
• search_search (الأداة search): تنشئ طلبات بحث GAQL SearchStream وتنفّذها من مَعلمات منظَّمة (customer_id وresource وfields، بالإضافة إلى المَعلمات الاختيارية conditions وorderings وlimit وlogin_customer_id) بدلاً من سلسلة GAQL أولية. يُلحق كل طلب بحث PARAMETERS omit_unselected_resource_names=true لجلب سمات الموارد والمقاييس والشرائح والميزانيات والحالة بشكل واضح.
• metadata_get_resource_metadata (الأداة get_resource_metadata): تستردّ هذه الأداة السمات والمقاييس وشرائح الجمهور القابلة للاختيار والفلترة والترتيب لنوع مورد في Google Ads API (مثل "campaign"). استخدِم هذه البيانات الوصفية لاستكشاف حقول طلبات البحث الصالحة، بما في ذلك المقاييس وشرائح الجمهور المُضافة في الإصدارات الثانوية مثل الإصدار 26.2، قبل استدعاء الأداة search_search.

أدوات التغيير (متوافقة جزئيًا)

• assets_create_asset (الأداة create_asset): تُنشئ مواد عرض مستقلة في "إعلانات Google" مع مَعلمات مخصّصة لأنواع مواد العرض TEXT وIMAGE وYOUTUBE_VIDEO وSITELINK وCALLOUT وSTRUCTURED_SNIPPET. مرِّر قاموس extra_params لأنواع AssetService الأخرى القابلة للتغيير (مثل PRICE أو PROMOTION أو CALL أو BUSINESS_MESSAGE)، وأدرِج final_urls على مستوى الجذر إلى جانب sitelink_link_text لمواد عرض SITELINK. تعمل مسارات الملفات على الجهاز (image_asset_path) في وضع stdio على الجهاز فقط. بالنسبة إلى عمليات النشر عن بُعد عبر HTTP، يجب تمرير المَعلمة image_asset_data المرمَّزة بترميز base64 مع ضبط image_asset_mime_type على IMAGE_PNG أو IMAGE_JPEG أو IMAGE_GIF (حتى 20 ميغابايت).
• assets_upload_video_asset (الأداة upload_video_asset): تحمّل ملف فيديو محلي (.3gp أو .avi أو .flv أو .mkv أو .mov أو .mp4 أو .mpeg أو .mpg أو .ogg أو .webm أو .wmv) إلى YouTube من خلال Google Ads API في وضع stdio المحلي فقط. يُعدّ كل من video_title وvideo_description من المَعلمات المطلوبة، ويتم ضبط الخصوصية تلقائيًا على UNLISTED (أو PUBLIC في قنوات العلامات التجارية التي يملكها المعلِنون والتي تستخدم بروتوكول OAuth للمستخدمين). تعرض هذه الأداة قيمة video_upload_id (واسم المورد) في "إعلانات Google"، وليس video_id المكوّن من 11 حرفًا في YouTube. يمكنك البحث عن "you_tube_video_upload" باستخدام أداة "search_search" (مع الفلترة حسب "you_tube_video_upload.video_upload_id") حتى ‎you_tube_video_upload.state = 'PROCESSED'. بعد ذلك، مرِّر you_tube_video_upload.video_id كمَعلمة youtube_video_id إلى assets_create_asset (asset_type="YOUTUBE_VIDEO").
• labels_manage_labels (الأداة manage_labels): تتيح إنشاء تصنيفات الحسابات وتعديلها وإزالتها، بما في ذلك الاسم والوصف ولون الخلفية السداسي العشري.
• labels_manage_label_associations (الأداة manage_label_associations): تتيح عمليات ربط التصنيفات CREATE وREMOVE (لا تتيح UPDATE) في الموارد CAMPAIGN وCUSTOMER وAD_GROUP وAD_GROUP_CRITERION. بالنسبة إلى موارد CUSTOMER، تكون السمة resource_id اختيارية ويتم ضبطها تلقائيًا على customer_id. يمكنك تمرير معرّف {ad_group_id}~{criterion_id} مركّب لموارد AD_GROUP_CRITERION، وإزالة عمليات الربط من خلال تمرير resource_id وlabel_id أو association_resource_name. لا يمكن استخدام تصنيفات AD_GROUP_AD على مستوى الإعلان.

المراجع

يتيح الخادم الوصول إلى أربعة موارد MCP بإذن بالقراءة فقط تظل متاحة بغض النظر عن إعدادات tools_config.yaml:

• resource://discovery-document: نظرة عامة على JSON REST discovery لموارد Google Ads API وطرق الخدمة والمخططات وهي مكمّلة لأداة metadata_get_resource_metadata التي تعرض حقول طلبات البحث في GAQL التي يمكن اختيارها وفلترتها وترتيبها.
• resource://metrics: مستندات مرجعية بتنسيق HTML لمقاييس Google Ads API
• resource://segments: مستندات مرجعية بتنسيق HTML لشرائح Google Ads API
• resource://release-notes: ملاحظات إصدار HTML Google Ads API التي تتناول تغييرات الإصدار والميزات الجديدة

سير عمل الأمان القائم على الاقتراح والتأكيد

تفرض كل أداة تعديل (assets_create_asset وassets_upload_video_asset وlabels_manage_labels وlabels_manage_label_associations) سير عمل من خطوتين للاقتراح والتأكيد للمساعدة في منع التعديلات غير المقصودة على الحساب:

1. Propose (validate_only=True، الإعداد التلقائي): يتم التحقّق من صحة الإدخالات بدون تطبيق التغييرات. تنفّذ أدوات مواد العرض والتصنيفات عملية تشغيل تجريبي مباشرةً لواجهة Google Ads API validate_only. بما أنّ YouTubeVideoUploadService لا يتضمّن وضع التشغيل التجريبي، يتحقّق assets_upload_video_asset من صحة الملف المحلي ويربط حجمه والطابع الزمني لتعديله. تُعرِض كل أداة إدخالات change_items يمكن لشخص عادي قراءتها وملخّص checksum SHA-256 بدون حالة مرتبط بمَعلمة customer_id وحمولة الطلب.
2. التأكيد (validate_only=False): بعد عرض قائمة change_items والحصول على موافقتك، يستدعي الوكيل الأداة مرة أخرى باستخدام validate_only=False، ومَعلمة customer_id والوسيطات المتطابقة، وقيمة checksum من الخطوة 1. يرفض الخادم أي مجموع اختباري مفقود أو غير متطابق قبل تعديل الحساب.

ضبط مساحات أسماء الأدوات ووضع القراءة فقط

يجمع الخادم ملف tools_config.yaml تلقائيًا مع تفعيل جميع فئات الأدوات الخمس (customers وsearch وmetadata وlabels وassets). يمكنك تخصيص tools_config.yaml لتفعيل أو إيقاف أدوات أو مساحات أسماء فردية بشكل انتقائي، أو تغيير بادئات مساحات الأسماء أو إزالتها، أو فرض عملية نشر للقراءة فقط بشكل صارم.

عند بدء التشغيل، يحلّ الخادم tools_config.yaml بالترتيب التالي:

1. مسار صريح في متغيّر البيئة GOOGLE_ADS_MCP_TOOLS_CONFIG (يُنصح به لمضيفي stdio المحليين الذين يمكن أن يختلف دليل العمل لديهم عن مجلد مشروعك).
2. ملف tools_config.yaml في دليل العمل الحالي للخادم
3. ملف tools_config.yaml التلقائي المضمَّن في الحزمة

إذا كان GOOGLE_ADS_MCP_TOOLS_CONFIG يشير إلى ملف مفقود، أو إذا كان أي ملف إعداد تم حله غير صالح، يظهر خطأ في الخادم عند بدء التشغيل بدلاً من الرجوع إلى الإعدادات التلقائية.

يفرض ملف tools_config.yaml التالي الحد الأدنى من النشر للقراءة فقط:

namespaces:
  customers: true
  search: true
  metadata: true
  labels: false
  assets: false

يخصّص ملف tools_config.yaml التالي البادئات ويفلتر الأدوات الفردية (على سبيل المثال، عرض أداة create_asset base64 على Cloud Run مع إيقاف أداة upload_video_asset المتوفّرة على الجهاز فقط):

namespaces:
  # Default prefix ("customers_list_accessible_customers")
  customers: true

  # Empty prefix mounts unprefixed tool names ("search")
  search: ""

  # Custom prefix ("schema_get_resource_metadata")
  metadata: "schema"

  # Enable only specific tools in a multi-tool category
  assets:
    enabled_tools:
      - create_asset

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

جرِّب الطلبات التالية في عميل MCP بعد ربط الخادم.

اسأل عن المهام التي يمكن للخادم تنفيذها

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

إنشاء مواد العرض وتحميل الفيديوهات وإدارة التصنيفات

Create a callout asset with the text "Free Shipping" for account 1234567890

Upload /path/to/promo.mp4 with title "Summer Sale" and description "Summer promo video" for account 1234567890

Create a label named "Q4 Promo" with background color #34A853 and apply it to campaign 9876543210 in account 1234567890

النشر على Google Cloud

لمشاركة خادم MCP مع عدة وكلاء أو تشغيله كخدمة ويب، يمكنك استضافته على Google Cloud Run أو مقدّم خدمة بنية أساسية سحابية آخر بدلاً من تشغيله محليًا.

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

1. مشروع على Google Cloud تم تفعيل Google Ads API فيه (راجِع المتطلبات الأساسية للحصول على إذن بالإصدار العلني).

2. تثبيت أداة سطر الأوامر gcloud والمصادقة عليها وضبطها باستخدام مشروع نشط:

   gcloud config set project PROJECT_ID
   

   غيِّر القيم في السلسلة على الشكل التالي:

   • ‫PROJECT_ID: رقم تعريف مشروعك على Google Cloud

إنشاء صورة Docker وإرسالها

استخدِم Cloud Build لإنشاء نسخة الحاوية وإرسالها إلى Artifact Registry بدون تثبيت Docker على جهازك:

1. أنشئ مستودعًا في Artifact Registry:

   gcloud artifacts repositories create mcp-servers \
     --repository-format=docker --location=us-central1
   

2. أنشِئ الصورة وأرسِلها من علامة إصدار في مستودع GitHub (أو من . في عملية دفع محلية إذا خصّصت Dockerfile أو tools_config.yaml):

   gcloud builds submit https://github.com/googleads/google-ads-mcp \
     --git-source-revision=v0.0.6 \
     --tag=us-central1-docker.pkg.dev/PROJECT_ID/mcp-servers/google-ads-mcp:v0.0.6
   

   غيِّر القيم في السلسلة على الشكل التالي:

   • ‫PROJECT_ID: رقم تعريف مشروعك على Google Cloud

   أعِد إنشاء الصورة وإعادة نشرها كلما حدّثت google-ads-mcp أو رقّيت مكتبة برامج Python المجمّعة google-ads لإصدارات Google Ads API الجديدة (مثل الإصدار 26.2).

النشر على Google Cloud Run

اضبط متغيرات البيئة والرموز السرية التالية لخدمة Cloud Run:

• ‫GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: معرِّف عميل تطبيق الويب لبروتوكول OAuth 2.0 من مشروعك على Google Cloud الذي تم تفعيل واجهة برمجة التطبيقات فيه لمصادقة OAuth على مستوى التطبيق. أكمِل خطوات إعداد 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). يحدّد Cloud Run عنوان URL هذا أثناء عملية النشر الأولية، لذا يجب النشر بدون هذا المتغيّر أولاً ثم تحديث الخدمة بعد ذلك.
• GOOGLE_ADS_MCP_JWT_SIGNING_KEY (يُنصح به لخدمة Cloud Run المتعدّدة المثيلات): رمز سرّي دائم يوقّع رموز JWT في FastMCP على مستوى عمليات إعادة تشغيل الحاويات والتوسيع الأفقي.
• GOOGLE_ADS_MCP_STORAGE_TYPE (يُنصح به لخدمة Cloud Run المتعددة النُسخ): الخلفية الثابتة لعمليات تسجيل عملاء OAuth والرموز المميّزة (redis مع GOOGLE_ADS_MCP_STORAGE_REDIS_URL أو firestore). بما أنّ v0.0.6 Dockerfile الأساسي يثبّت الخلفية في الذاكرة فقط، يجب تثبيت py-key-value-aio[redis] أو .[firestore] في Dockerfile مخصّص أولاً. يتطلّب استخدام firestore أيضًا قاعدة بيانات Firestore ودور roles/datastore.user في "إدارة الهوية وإمكانية الوصول" (IAM) في حساب خدمة Cloud Run. لإجراء اختبار على مثيل واحد باستخدام مساحة تخزين في الذاكرة، مرِّر --max-instances=1.
• GOOGLE_ADS_LOGIN_CUSTOMER_ID (اختياري): الرقم التعريفي التلقائي للعميل الإداري المكوّن من 10 أرقام (بدون واصلات) والذي يتم استخدامه عندما تحذف طلبات الأداة المَعلمة login_customer_id.
• GOOGLE_ADS_MCP_TOOLS_CONFIG (اختياري): مسار الحاوية إلى ملف tools_config.yaml مخصّص (على سبيل المثال، يتم تحميله من Secret Manager في /etc/mcp/tools_config.yaml لفرض وضع القراءة فقط بدون إعادة إنشاء الصورة). يُرجى الاطّلاع على ضبط مساحات أسماء الأدوات ووضع القراءة فقط.

يُرجى تخزين GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET وGOOGLE_ADS_MCP_JWT_SIGNING_KEY في Secret Manager ونشر الخدمة في Google Cloud Run:

gcloud run deploy google-ads-mcp \
  --image=us-central1-docker.pkg.dev/PROJECT_ID/mcp-servers/google-ads-mcp:v0.0.6 \
  --platform=managed \
  --region=us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=CLIENT_ID" \
  --set-secrets="GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=MCP_OAUTH_CLIENT_SECRET:latest,GOOGLE_ADS_MCP_JWT_SIGNING_KEY=MCP_JWT_SIGNING_KEY:latest"

بعد أن تُكمل 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://CLOUD_RUN_SERVICE_URL"

غيِّر القيم في السلسلة على الشكل التالي:

• ‫PROJECT_ID: رقم تعريف مشروعك على Google Cloud
• ‫CLIENT_ID: معرّف عميل تطبيق الويب OAuth 2.0
• ‫MCP_OAUTH_CLIENT_SECRET: اسم سرّ Secret Manager الذي يخزّن سرّ عميل OAuth 2.0.
• ‫MCP_JWT_SIGNING_KEY: اسم البيانات السرية في Secret Manager التي تخزّن مفتاح توقيع JWT
• ‫CLOUD_RUN_SERVICE_URL: اسم المضيف المخصّص لخدمة Cloud Run (على سبيل المثال، google-ads-mcp-xyz-uc.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، يفرض الخادم استخدام Google OAuth 2.0 في كل طلب ويعرض رمز حالة HTTP ‏401 Unauthorized للمتصلين الذين لم تتم مصادقتهم. يتم تنفيذ كل طلب أداة ضمن هوية OAuth الخاصة بالمتصل الذي تمت مصادقته.
• يتطلب حذف --allow-unauthenticated من المتصلين تمرير رموز تعريف 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 الخاص بالخدمة مع المسار /mcp (على سبيل المثال، https://google-ads-mcp-xyz-uc.a.run.app/mcp). اختَر مصادقة OAuth 2.0 باستخدام معرّف عميل OAuth وسر العميل، وتأكَّد من أنّ معرّف الموارد المنتظم (URI) لطلب معاودة الاتصال الخاص بالعميل مُدرَج في معرّفات الموارد المنتظمة (URI) لإعادة التوجيه المصرَّح بها لعميل OAuth.
• البرامج التي لا تتيح استخدام بروتوكول OAuth: تتلقّى البرامج التي لا تتيح استخدام مسارات HTTP OAuth رمز حالة HTTP ‏401 Unauthorized. بالنسبة إلى هذه البرامج، استخدِم إعدادات stdio المحلية بدلاً من ذلك.

يضبط المثال التالي أداة سطر الأوامر gemini في ~/.gemini/settings.json (بالنسبة إلى Google Antigravity في ~/.gemini/config/mcp_config.json، استبدِل "httpUrl" بـ "serverUrl" أو "url"):

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://CLOUD_RUN_SERVICE_URL/mcp"
    }
  }
}

غيِّر القيم في السلسلة على الشكل التالي:

• ‫CLOUD_RUN_SERVICE_URL: اسم المضيف المخصّص لخدمة Cloud Run (على سبيل المثال، google-ads-mcp-xyz-uc.a.run.app)

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

• تثبيت مهارات وكيل Google Ads API
• مساعد الدراسة عن Google Ads API Developer Assistant
• تثبيت Google Ads API Developer Assistant واستخدامه