‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

שרת ה-MCP של Google Ads: מדריך שילוב למפתחים

‫Model Context Protocol (MCP) הוא תקן פתוח שמאפשר למודלים גדולים של שפה (LLM) לקיים אינטראקציה מאובטחת עם נתונים ואפליקציות חיצוניים. שרת ה-MCP של Google Ads מספק גשר סטנדרטי ל-Google Ads API. הוא מאפשר לסוכני AI לאחזר ולנתח נתונים בחשבון, ליצור נכסים, להעלות סרטונים ולנהל תוויות באמצעות שפה טבעית.

מקורות מידע ותמיכה מהקהילה

מאגר GitHub: במאגר google-ads-mcp אפשר למצוא הדגמות ודוגמאות, לדווח על באגים או להציע תכונות.

אפשר להשתמש בכרטיסייה Issues כדי לדווח על באגים ולשלוח הגשת בקשה להוספת תכונה.
קהילה: אתם יכולים להצטרף לערוץ #ads-api-ai-tools בקהילת הפרסום של Google ב-Discord.

סקירה טכנית

כשמשלבים את שרת ה-MCP של Google Ads, לא צריך לכתוב קוד בהתאמה אישית לאימות של Google Ads API, לאחזור משאבים, לניתוח נתונים ולשינויים נתמכים בנכסים או בתוויות. השרת חושף כלים שניתן להפעיל ומשאבים להפניה (ראו יכולות עיקריות) שמודל שפה גדול (LLM) יכול לבדוק ולהפעיל.

מפרטים עיקריים

פרוטוקול: MCP‏ (Model Context Protocol)
מצב: קריאה ושינוי חלקי (יצירת נכסים, העלאת סרטונים וניהול תוויות עם אימות מסוג הצעה ואישור, או מצב קריאה בלבד שניתן להגדרה)
שפה: Python 3.10 ואילך
‫Transport: קלט/פלט סטנדרטי (stdio) או HTTP בסטרימינג (streamable-http ב-Cloud Run)
אימות: Application Default Credentials (פרטי כניסה של משתמש OAuth 2.0 או חשבון שירות) ל-stdio מקומי, או פרטי כניסה של אפליקציית אינטרנט OAuth 2.0 ל-HTTP מרוחק

איך פועלת לולאת האינטראקציה

בקשה: אתם שולחים הנחיה כמו "מהם הביצועים ברמת הקמפיין שלי השבוע?" או "צור נכס יתרונות מרכזיים למבצע הקיץ שלנו".
גילוי: מודל ה-LLM בודק את הכלים והמשאבים שזמינים לו ובוחר כלי מתאים של google-ads-mcp.
אימות הרצה או הרצה ללא שינוי: כלי קריאה שולחים שאילתות ישירות ל-Google Ads API. כלי המוטציה פועלים קודם במצב הצעה (validate_only=True) כדי לאמת את הקלט בלי לבצע שינויים (ראו תהליך עבודה בטוח של הצעה ואישור).
הזרקת הקשר: שרת ה-MCP מחזיר תוצאות שאילתה מובנות, או רשומות change_items מוצעות ותקציר אימות של checksum, לחלון ההקשר של ה-LLM.
תשובה ואישור: ה-LLM מציג תשובה או מבקש מכם לאשר את השינויים המוצעים. אחרי האישור, ה-LLM קורא שוב לכלי המוטציה עם validate_only=False והערך התואם של checksum כדי לבצע את השינוי.

שנתחיל?

כדי להגדיר ולהפעיל את שרת ה-MCP של Google Ads באופן מקומי, פועלים לפי השלבים הבאים. כדי לפרוס שירות מרוחק משותף, קראו את המאמר פריסה ב-Google Cloud.

דרישות מוקדמות

לפני שמגדירים את השרת, צריך לבצע את הפעולות הבאות בסביבה המקומית ובמסוף Google Cloud:

‫Google Cloud project: יוצרים או בוחרים פרויקט ב-Google Cloud שבו מופעל Google Ads API. הפעלת ה-API מעניקה גישת בדיקה לבדיקת תהליכי עבודה של קריאה ושינוי בחשבונות בדיקה. כדי לגשת לחשבונות פעילים, צריך לבדוק בדף הסקירה הכללית של Google Ads API אם יש לכם הרשאת גישה מסוג Explorer, הרשאת גישה בסיסית או הרשאת גישה רגילה, או להגיש בקשה לאחת מרמות הגישה האלה. אחרת, הקריאות בסביבת הייצור נכשלות עם השגיאה AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION. ‫Google הוציאה משימוש את טוקן הפיתוח (GOOGLE_ADS_DEVELOPER_TOKEN) ב-9 בספטמבר 2026. רמת הגישה ל-API נקבעת לפי הפרויקט בענן של Google שבבעלותו נמצאים לקוח ה-OAuth או חשבון השירות.
פרטי כניסה: מצב stdio מקומי מבצע אימות באמצעות Application Default Credentials (ADC) מקובץ JSON של סוד לקוח ב-OAuth 2.0 או מחשבון שירות בפרויקט בענן שלכם. מגדירים את משתנה הסביבה GOOGLE_CLOUD_PROJECT כשצריך לציין את מכסת ברירת המחדל או את הפרויקט של ADC. בפריסות מרחוק של streamable-http, צריך מזהה לקוח וסוד לקוח של אפליקציית אינטרנט ב-OAuth 2.0 (ראו פריסה ב-Google Cloud Run).
תוכנה מקומית (למצב stdio): מתקינים את Python 3.10 ואילך, את pipx ואת כלי שורת הפקודה gcloud (שמשמש ליצירת קובצי ADC של משתמשים).

הגדרות אישיות

יוצרים Application Default Credentials (ADC) באמצעות לקוח OAuth מהפרויקט ב-Google Cloud שבו ה-API מופעל, וכוללים את ההיקף של 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.
מוסיפים את השרת לקובץ התצורה של 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.
- ‫PATH_TO_CREDENTIALS_JSON: הנתיב לקובץ ה-JSON של ה-ADC שהודפס בשלב 1, או לקובץ ה-JSON של המפתח של חשבון השירות. אפשר להשמיט את GOOGLE_APPLICATION_CREDENTIALS כשמשתמשים במיקום ברירת המחדל של קובץ ה-ADC‏ gcloud.
כדי לגשת לחשבונות לקוח דרך חשבון ניהול, צריך להגדיר את GOOGLE_ADS_LOGIN_CUSTOMER_ID (10 ספרות, בלי מקפים) ב-env, או להעביר את הפרמטר login_customer_id בקריאות API לכלי ספציפי.

אופציונלי: הוספת מיומנויות לסוכן והפעלת Developer Assistant

שרת ה-MCP של Google Ads נותן ללקוח ה-AI גישה בזמן אמת לנתוני הדיווח בחשבון, וגם לכלים ליצירת נכסים, להעלאת סרטונים ולניהול תוויות. כדי לעזור לסוכן ליצור שאילתות תקינות בשפת השאילתות של Google Ads‏ (GAQL) ולזהות שינויים בביצועים של החשבון, כדאי לשלב את שרת ה-MCP עם הכלים הבאים. הכלים האלה גם יוצרים קוד של ספריית לקוח, כמו סקריפטים לקישור נכסים שנוצרו לקמפיינים או לביצוע שינויים אחרים שלא נתמכים:

‫מיומנויות של סוכן Google Ads API: מודולים ניידים של תהליכי עבודה (כולל google-ads-api-mcp-setup,‏ google-ads-api-account-diagnostics ו-google-ads-api-quickstart) שעוזרים לסוכן להשתמש בשרת MCP של Google Ads עם פחות תקורה של טוקנים. כדי להתקין אותם, מריצים את הפקודה הבאה (נדרש 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 Ads שלמשתמש המאומת יש גישה ישירה אליהם.
‫search_search (הכלי search): יוצר ומריץ שאילתות GAQLSearchStream מפרמטרים מובְנים (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 Ads עם פרמטרים ייעודיים לסוגי הנכסים 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 (עד 20MB).
‫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 Ads (ושם משאב), ולא את הערך של video_id ב-YouTube שמורכב מ-11 תווים. שולחים שאילתה ל-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 ברמת המודעה.

הערה: התמיכה ב-Mutate כוללת רק יצירת נכסים נפרדים, העלאות של סרטונים וניהול תוויות. השרת לא יכול לקשר נכסים לקמפיינים, לקבוצות של מודעות או לקבוצות נכסים, או לקבוע הגדרות של אוטומציה של נכסים ברמת המודעה (כמו OVERLAY_TEXT_ON_VIDEOS בגרסה 26.2). הוא גם לא יכול ליצור, לשנות, להשהות או להפעיל קמפיינים, קבוצות של מודעות, מודעות, תקציבים או הצעות מחיר. במקרה של מוטציות שלא נתמכות, צריך להתאים את השרת לכלי עזר ליצירת קוד (ראו הוספת מיומנויות לנציג והכלי Developer Assistant).

מקורות מידע

השרת חושף ארבעה משאבי 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: הערות המוצר של Google Ads API בפורמט HTML, שכוללות את השינויים בגרסאות ואת התכונות החדשות.

תהליך עבודה בטיחותי של הצעה ואישור

כל כלי לשינוי (assets_create_asset,‏ assets_upload_video_asset,‏ labels_manage_labels ו-labels_manage_label_associations) אוכף תהליך עבודה דו-שלבי של הצעה ואישור כדי למנוע שינויים לא מכוונים בחשבון:

‫Propose (validate_only=True, ברירת מחדל): אימות של הקלט בלי לשמור את השינויים. כלי הנכסים והתוויות מריצים הרצה יבשה של Google Ads API ב-validate_only. ב-YouTubeVideoUploadService אין מצב פרימטר לבדיקות, ולכן assets_upload_video_asset מאמת את הקובץ המקומי ומקשר את הגודל ואת חותמת הזמן של השינוי שלו. כל כלי מחזיר רשומות change_items קריאות לאנשים ותקציר SHA-256 checksum ללא שמירת מצב (stateless) שקשור לפרמטר customer_id ולמטען הייעודי (payload) של הבקשה.
אישור (validate_only=False): אחרי שהסוכן מציג את הרשימה change_items ומקבל את האישור שלכם, הוא קורא שוב לכלי עם validate_only=False, הפרמטר והארגומנטים הזהים של customer_id והערך checksum משלב 1. השרת דוחה כל סיכום ביקורת (checksum) חסר או לא תואם לפני שינוי החשבון.

הגדרת מרחבי שמות של כלים ומצב קריאה בלבד

השרת כולל קובץ tools_config.yaml שמוגדר כברירת מחדל, שבו כל חמש הקטגוריות של הכלים (customers,‏ search,‏ metadata,‏ labels ו-assets) מופעלות. אפשר להתאים אישית את tools_config.yaml כדי להפעיל או להשבית באופן סלקטיבי כלים או מרחבי שמות ספציפיים, לשנות או להסיר קידומות של מרחבי שמות, או לאכוף פריסה לקריאה בלבד.

בזמן ההפעלה, השרת פותר את tools_config.yaml בסדר הבא:

נתיב מפורש במשתנה הסביבה GOOGLE_ADS_MCP_TOOLS_CONFIG (מומלץ למארחים מקומיים של stdio, שספריית העבודה שלהם יכולה להיות שונה מתיקיית הפרויקט).
קובץ tools_config.yaml בספריית העבודה הנוכחית של השרת.
קובץ ברירת המחדל 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 או בספק אחר של תשתית ענן, במקום להריץ אותו באופן מקומי.

דרישות מוקדמות

פרויקט ב-Google Cloud שבו Google Ads API מופעל (בקטע דרישות מוקדמות מפורטות הדרישות לקבלת גישה לסביבת הייצור).
כלי שורת הפקודה gcloud מותקן, מאומת ומוגדר עם פרויקט פעיל:
```
gcloud config set project PROJECT_ID
```
מחליפים את מה שכתוב בשדות הבאים:
- PROJECT_ID: מזהה הפרויקט בענן של Google.

יצירה והעברה בדחיפה של קובץ אימג' של Docker

משתמשים ב-Cloud Build כדי ליצור את קובץ האימג' של הקונטיינר ולהעביר אותו בדחיפה ל-Artifact Registry, בלי להתקין את Docker באופן מקומי:

יוצרים מאגר ב-Artifact Registry:

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

יוצרים את קובץ האימג' ושולחים אותו מתג גרסה במאגר GitHub (או מ-. ב-checkout מקומי אם התאמתם אישית את 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.
צריך לבנות מחדש ולפרוס מחדש את קובץ האימג' בכל פעם שמעדכנים את google-ads-mcp או משדרגים את ספריית הלקוח של google-ads Python שמצורפת לחבילה לגרסאות חדשות של Google Ads API (כמו גרסה 26.2).

פריסה ב-Google Cloud Run

מגדירים את משתני הסביבה והסודות הבאים לשירות Cloud Run:

‫GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: מזהה הלקוח של אפליקציית האינטרנט ב-OAuth 2.0 מהפרויקט בענן ב-Google Cloud שבו הופעל ה-API, לצורך אימות OAuth ברמת האפליקציה. מבצעים את השלבים הבאים להגדרת OAuth:
- מוסיפים את כתובות ה-URI המורשות להפניה אוטומטית לכל לקוחות ה-AI שרוצים לחבר (למשל 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 בקטע APIs & Services > OAuth consent screen > Data Access (Add or remove scopes).
- אם סטטוס הפרסום של מסך ההסכמה של OAuth מוגדר כ-Testing (ברירת המחדל), מוסיפים את חשבונות Google שמתחברים לשרת ה-MCP בתור Test users בקטע APIs & Services > OAuth consent screen > Audience (Test users > + Add users).
‫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 ספרות (בלי מקפים). המערכת משתמשת בו כשקריאות API לכלי לא כוללות את הפרמטר 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.
‫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), כדי שלקוחות AI חיצוניים יוכלו להתחבר בלי אסימונים של חשבון שירות ב-Google Cloud. במקום זאת, האימות מועבר לשכבת האפליקציה:

כשמגדירים את GOOGLE_ADS_MCP_OAUTH_CLIENT_ID ו-GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET, השרת אוכף את Google OAuth 2.0 בכל בקשה ומחזיר קוד סטטוס של HTTP‏ 401 Unauthorized למבצעי קריאה לא מאומתים. כל קריאת API לכלי מתבצעת במסגרת זהות ה-OAuth של הגורם המאומת שמבצע את הקריאה.
אם משמיטים את --allow-unauthenticated, המתקשרים צריכים להעביר אסימוני זהות של Google Cloud OIDC בכל בקשה. לקוחות AI רגילים (כמו Claude ו-ChatGPT) משתמשים ב-OAuth של משתמשי קצה ולא באסימוני IAM של Google Cloud, ולכן חיבורים ישירים דורשים את --allow-unauthenticated בשילוב עם OAuth ברמת האפליקציה.

הגדרת לקוח ה-MCP

אחרי הפריסה, מגדירים את לקוח ה-MCP עם כתובת ה-URL של שירות Cloud Run. מכיוון שהשרת אוכף את OAuth 2.0, הלקוח חייב לתמוך בתהליך MCP OAuth או לספק טוקן למוכ"ז מורשה:

לקוחות שתומכים ב-OAuth: בלקוחות שתומכים בגילוי MCP OAuth (כמו Antigravity), החיבור מפעיל הודעת אימות מ-Google כדי להעניק את ההיקף https://www.googleapis.com/auth/adwords (מוצג בתור .../auth/adwords במסוף Google Cloud).
פלטפורמות AI של צד שלישי (Claude, ‏ChatGPT): בהגדרות המחבר של הלקוח, מוסיפים מחבר בהתאמה אישית שמפנה לכתובת ה-URL של השירות עם הנתיב /mcp (לדוגמה, https://google-ads-mcp-xyz-uc.a.run.app/mcp). בוחרים אימות OAuth 2.0 עם מזהה הלקוח וסוד הלקוח ב-OAuth, ומוודאים שכתובת ה-URI להחזרת קריאה (callback) של הלקוח נמצאת בכתובות ה-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).

שרת ה-MCP של Google Ads: מדריך שילוב למפתחים קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

מקורות מידע ותמיכה מהקהילה

סקירה טכנית

מפרטים עיקריים

איך פועלת לולאת האינטראקציה

שנתחיל?

דרישות מוקדמות

הגדרות אישיות

אופציונלי: הוספת מיומנויות לסוכן והפעלת Developer Assistant

היכולות המרכזיות

כלי קריאה

כלי שינוי (תמיכה חלקית)

מקורות מידע

תהליך עבודה בטיחותי של הצעה ואישור

הגדרת מרחבי שמות של כלים ומצב קריאה בלבד

הנחיות לדוגמה להתחלת העבודה

איך שואלים מה השרת יכול לעשות

שאלות על לקוחות

שאלות על קמפיינים

יצירת נכסים, העלאת סרטונים וניהול תוויות

פריסה ב-Google Cloud

דרישות מוקדמות

יצירה והעברה בדחיפה של קובץ אימג' של Docker

פריסה ב-Google Cloud Run

מודל אימות ואבטחה

הגדרת לקוח ה-MCP

השלבים הבאים

שרת ה-MCP של Google Ads: מדריך שילוב למפתחים