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

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

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

סקירה טכנית

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

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

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

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

  1. בקשה: משתמש שולח שאילתה כמו "How is my campaign performance this week?‎" (מהם הביצועים ברמת הקמפיין שלי השבוע?).
  2. גילוי: ה-LLM בודק את הכלים הזמינים ומזהה את יכולות החיפוש של google-ads-mcp.
  3. ביצוע: שרת ה-MCP מריץ את הלוגיקה של Python כדי לשלוח שאילתה ל-Google Ads API.
  4. הזרקת הקשר: תוצאות מובְנות מוחזרות לחלון ההקשר של ה-LLM.
  5. תשובה: מודל ה-LLM מסנתז את הנתונים לתשובה קריאה לאנשים.

שנתחיל?

כדי להגדיר את שרת ה-MCP של Google Ads ולהשתמש בו, פועלים לפי השלבים הבאים.

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

לפני ההגדרה, ודאו שיש לכם את פרטי הכניסה הבאים ממסוף Google Cloud:

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

כדי לשלב את השרת במארח שתואם ל-MCP, מוסיפים את הרשומה הבאה לקובץ התצורה של MCP במארח, למשל settings.json, ומפנים את GOOGLE_APPLICATION_CREDENTIALS לקובץ ה-JSON של ADC (או מגדירים את ברירת המחדל של ADC באמצעות 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"
      }
    }
  }
}

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

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

  • ‫מיומנויות של סוכן Google Ads API: מודולים ניידים של הוראות ותהליכי עבודה ספציפיים ל-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? מוסבר איך הוא פועל, ובמדריך ההתקנה מוסבר איך להתקין אותו.

פריסה ב-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, עם רמות הגישה המתאימות ל-API.
  • ‫GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: מזהה הלקוח של OAuth 2.0 (מוגדר כאפליקציית אינטרנט בפרויקט ב-Google Cloud) לאימות 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). מכיוון ש-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), כדי שלקוחות AI חיצוניים יוכלו להתחבר בלי צורך באסימונים של חשבון שירות ב-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, שמחייב את הגורמים שמבצעים את הקריאה להעביר אסימוני זהות של Google Cloud OIDC בכל בקשה. לקוחות AI רגילים (כמו Claude ו-ChatGPT) מבצעים אימות באמצעות OAuth של משתמשי קצה, ולא באמצעות אסימוני זהות של Google Cloud IAM. לכן, כדי ליצור חיבורים ישירים מהפלטפורמות האלה, צריך להשתמש ב---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 של 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 Ads ושמות החשבונות שנגישים למשתמש המאומת.
  • ‫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

השלבים הבאים