سرور MCP گوگل ادز: راهنمای ادغام توسعه‌دهندگان

پروتکل زمینه مدل (MCP) یک استاندارد باز است که مدل‌های زبان بزرگ (LLM) را قادر می‌سازد تا به طور ایمن با داده‌ها و برنامه‌های خارجی تعامل داشته باشند. سرور MCP گوگل ادز یک پل استاندارد به API گوگل ادز ارائه می‌دهد که به عوامل هوش مصنوعی اجازه می‌دهد داده‌های کمپین را با استفاده از زبان طبیعی تجزیه و تحلیل و بازیابی کنند.

منابع و پشتیبانی جامعه

نمای کلی فنی

با پیاده‌سازی این سرور MCP، نیاز به نوشتن «کد چسب» سفارشی برای احراز هویت API گوگل ادز، واکشی منابع و تجزیه داده‌ها را از بین می‌برید. این سرور ابزارهای خاصی را در اختیار قرار می‌دهد که یک LLM می‌تواند به صورت خودکار آنها را کشف و فراخوانی کند.

مشخصات کلیدی

  • پروتکل: MCP (پروتکل زمینه مدل)
  • حالت: فقط خواندنی (نسخه فعلی)
  • زبان: پایتون
  • انتقال: ورودی/خروجی استاندارد ( stdio )
  • احراز هویت: OAuth 2.0 یا حساب سرویس

نحوه عملکرد حلقه تعامل

  1. درخواست: کاربر سوالی مانند «عملکرد کمپین من این هفته چگونه است؟» ارسال می‌کند.
  2. کشف: LLM ابزارهای موجود خود را بررسی کرده و قابلیت‌های جستجوی google-ads-mcp را شناسایی می‌کند.
  3. اجرا: سرور MCP منطق پایتون زیربنایی را برای پرس‌وجو از API تبلیغات گوگل اجرا می‌کند.
  4. تزریق متن: نتایج ساختاریافته به پنجره متن LLM بازگردانده می‌شوند.
  5. پاسخ: LLM داده‌ها را به یک پاسخ قابل خواندن توسط انسان تبدیل می‌کند.

شروع کنید

برای پیکربندی و استفاده از سرور Google Ads MCP، این مراحل را دنبال کنید.

پیش‌نیازها

قبل از پیکربندی، مطمئن شوید که اطلاعات احراز هویت زیر را از کنسول توسعه‌دهندگان گوگل ادز دارید:

  • توکن توسعه‌دهنده: رشته دسترسی ۲۲ کاراکتری منحصر به فرد شما.
  • شناسه پروژه: شناسه پروژه Google Cloud شما.
  • اعتبارنامه‌های OAuth: یا یک جفت شناسه کلاینت/رمز کلاینت OAuth2، یا مجموعه‌ای از اعتبارنامه‌های پیش‌فرض برنامه .

پیکربندی

برای ادغام سرور در یک میزبان سازگار با MCP، ورودی زیر را به فایل پیکربندی MCP میزبان خود، مانند settings.json ، اضافه کنید. برای مکان دقیق و نام فایل این پیکربندی، به مستندات میزبان خود مراجعه کنید.

جی‌سون

{
  "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_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
      }
    }
  }
}

استقرار در فضای ابری گوگل

به جای میزبانی این سرور MCP به صورت محلی، می‌توانید آن را در Google Cloud Run یا هر زیرساخت ابری دیگری میزبانی کنید. این قابلیت در صورتی مفید است که بخواهید سرور را بین عوامل مختلف به اشتراک بگذارید یا آن را به عنوان یک سرویس وب اجرا کنید.

پیش‌نیازها

  1. یک پروژه ابری گوگل.

  2. ابزار خط فرمان gcloud نصب، احراز هویت و با یک پروژه فعال پیکربندی شده است:

    gcloud config set project YOUR_PROJECT_ID

ساخت و بارگذاری یک ایمیج داکر

شما می‌توانید از Cloud Build برای ساخت و ارسال ایمیج به Artifact Registry بدون نیاز به نصب Docker به صورت محلی استفاده کنید.

  1. ایجاد یک مخزن در رجیستری مصنوعات:

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

  2. تصویر را بسازید و ارسال کنید:

    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_ADS_DEVELOPER_TOKEN : توکن توسعه‌دهنده‌ای که می‌خواهید سرور MCP از آن استفاده کند.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID : شناسه کلاینت OAuth که می‌خواهید سرور MCP از آن استفاده کند.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET : رمز OAuth Client که می‌خواهید سرور MCP از آن استفاده کند.
  • GOOGLE_ADS_MCP_BASE_URL : آدرس اینترنتی پایه که سرور MCP شما از طریق آن قابل دسترسی است: این آدرس به طور خودکار توسط Google Cloud Run پس از اولین استقرار شما اختصاص داده می‌شود. می‌توانید متغیرهای محیطی را پس از استقرار به‌روزرسانی کنید.
  • FASTMCP_HOST : این مقدار را روی 0.0.0.0 تنظیم کنید تا FastMCP بتواند اتصالات را از همه آدرس‌های IP بپذیرد. 
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_DEVELOPER_TOKEN=YOUR_DEVELOPER_TOKEN,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,GOOGLE_ADS_MCP_BASE_URL=YOUR_BASE_URL,FASTMCP_HOST=0.0.0.0"

پیکربندی کلاینت MCP

پس از استقرار، پیکربندی کلاینت MCP خود (برای مثال، ~/.gemini/settings.json ) را برای استفاده از آدرس اینترنتی Cloud Run به‌روزرسانی کنید.

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://your-cloud-run-url.a.run.app/mcp"
    }
  }
}

قابلیت‌های اصلی (ابزارها)

این سرور ابزارهایی را که برای کشف حساب کاربری و گزارش عملکرد طراحی شده‌اند، در معرض نمایش قرار می‌دهد:

  • list_accessible_customers : فهرست شناسه‌های مشتری و نام‌های حساب کاربری گوگل ادز که برای کاربر احراز هویت‌شده قابل دسترسی هستند را برمی‌گرداند.
  • search : درخواست‌های زبان جستجوی گوگل ادز (GAQL) را برای دریافت معیارهای منابع، بودجه‌ها و وضعیت اجرا می‌کند.

  • get_resource_metadata : فراداده‌های مربوط به یک نوع منبع 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