שרת ה-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"
      }
    }
  }
}

פריסה ב-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, ולכן כל בקשה צריכה לכלול אסימוני זהות OIDC של Google Cloud. מכיוון שלקוחות AI רגילים (כמו Claude ו-ChatGPT) מבצעים אימות באמצעות OAuth של משתמש קצה ולא באמצעות טוקנים של זהויות Cloud 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 של Cloud Run עם הנתיב /mcp (לדוגמה, https://your-cloud-run-url.a.run.app/mcp), בוחרים באימות OAuth 2.0 (באמצעות מזהה הלקוח וסוד הלקוח שלכם ב-OAuth) ומוודאים שכתובת ה-URI של הקריאה החוזרת של הלקוח נוספה לכתובות ה-URI המורשות להפניה אוטומטית של לקוח ה-OAuth. (משתתפים בתוכנית הפיילוט של נקודת הקצה המתארחת יכולים גם לעיין במדריך להגדרת MCP מתארח).
  • לקוחות ללא תמיכה ב-OAuth: לקוחות שלא תומכים בתהליכי OAuth HTTP יקבלו תגובה לא מורשית מסוג 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: מריץ בקשות של Google Ads Query Language‏ (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