سرور Google Ads MCP: راهنمای یکپارچه‌سازی توسعه‌دهنده

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

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

• مخزن GitHub: در مخزن google-ads-mcp، نسخه‌های نمایشی و نمونه‌ها را پیدا کنید، اشکال‌ها را گزارش کنید، یا ویژگی پیشنهاد دهید.

  از برگه «مشکلات» برای گزارش اشکال و درخواست ویژگی استفاده کنید.

• انجمن: به کانال #ads-api-ai-tools در Google Advertising Community Discord بپیوندید.

نمای کلی فنی

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

مشخصات کلیدی

• پروتکل: MCP (پروتکل بافتار مدل)
• حالت: فقط خواندنی (نسخه کنونی)
• زبان: Python
• انتقال: ورودی/خروجی استاندارد (stdio) یا HTTP جاری‌سازی‌شدنی (streamable-http / Cloud Run)
• اصالت‌سنجی: OAuth 2.0 یا حساب سرویس

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

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

شروع کنید

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

پیش‌نیازها

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

• شناسه پروژه: شناسه پروژه Google Cloud شما (GOOGLE_PROJECT_ID). صفحه نمای کلی Google Ads API را بررسی کنید تا مطمئن شوید پروژه‌تان سطح دسترسی «کاوشگر»، «پایه»، یا «استاندارد» را دارد. اگر نه، برای یکی از این سطوح دسترسی درخواست دهید. توجه داشته باشید که نشان‌های توسعه‌دهنده (GOOGLE_ADS_DEVELOPER_TOKEN) در ۹ سپتامبر ۲۰۲۶ منسوخ شدند و دیگر در جدیدترین نسخه سرور Google Ads MCP لازم نیستند زیرا سطوح دسترسی به API با پروژه Google Cloud مرتبط است.
• اعتبارنامه OAuth: یا یک جفت «شناسه کارخواه»/«رمز کارخواه» OAuth 2.0، یا مجموعه‌ای از اعتبارنامه‌های پیش‌فرض برنامه.

پیکربندی

برای ادغام کردن سرور در میزبان سازگار با MCP، ورودی زیر را به فایل پیکربندی MCP میزبان خود، مانند settings.json، اضافه کنید و GOOGLE_APPLICATION_CREDENTIALS را به فایل ADC JSON خود ارجاع دهید (یا 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"
      }
    }
  }
}

اختیاری: عاملتان را به مهارت‌ها و «دستیار توسعه‌دهنده» مجهز کنید

سرور MCP در Google Ads به مشتری هوش مصنوعی شما دسترسی فقط خواندنی به داده‌های حساب زنده می‌دهد. برای کمک به عاملتان در ساختن پُرسمان‌های معتبر 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، که به نماینده شما آموزش می‌دهند چگونه به‌طور مؤثر و با سربار کمتر از سرور Google Ads MCP استفاده کند. آن‌ها را با یک فرمان نصب کنید (به Node.js نیاز دارد)، یا برای گزینه‌های Antigravity،‏ Claude Code،‏ Codex، و Cursor، راهنمای مهارت‌های عامل Google Ads API را ببینید:

  npx skills add google/skills/skills/ads
  

• دستیار توسعه‌دهنده Google Ads API: افزونه‌ای پیمانه‌ای برای Google Antigravity و Claude Code که بازرسی طرح‌واره Protobuf محلی، اعتبارسنجی GAQL برنامه‌ای، تولید کد کتابخانه مشتری (ازجمله دستورگان جهش)، و عیب‌یابی تبدیل آفلاین را ارائه می‌دهد. در «دستیار توسعه‌دهنده Google Ads API» چیست؟ با نحوه عملکرد آن آشنا شوید یا راهنمای نصب را دنبال کنید.

استقرار در 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 شما که دارای سطوح دسترسی مناسب به میانای برنامه‌سازی کاربردی است.
• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: شناسه کارخواه OAuth 2.0 (پیکربندی‌شده به‌عنوان برنامه وب در پروژه Google Cloud شما) برای اصالت‌سنجی OAuth در سطح برنامه. مطمئن شوید:
  • نشانی‌های وب هدایت مجاز مناسب را برای هر مشتری هوش مصنوعی که قصد اتصال آن را دارید (مانند 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: نشانی وب پایه عمومی که سرور MCP شما در آنجا قابل‌دسترسی است (برای مثال، https://google-ads-mcp-xyz-uc.a.run.app). چون Google Cloud Run این نشانی وب را درطول استقرار اولیه تولید می‌کند، ابتدا بدون این متغیر مستقر کنید، سپس سرویس را پس‌از استقرار به‌روز کنید.
• 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 استقرار را تکمیل کرد، نشانی وب سرویس اختصاص‌داده‌شده را بازیابی کنید و سرویس را با متغیر محیطی 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) را غیرفعال می‌کند تا مشتریان هوش مصنوعی خارجی بتوانند بدون نیاز به توکن‌های حساب سرویس Google Cloud متصل شوند. درعوض، اصالت‌سنجی به لایه برنامه واگذار می‌شود:

• وقتی GOOGLE_ADS_MCP_OAUTH_CLIENT_ID و GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET ارائه شوند، سرور MCP Google OAuth 2.0 را در همه درخواست‌های ورودی اعمال می‌کند و با پاسخ HTTP 401 تماس‌گیرندگان تأییدنشده را به‌چالش می‌کشد. همه درخواست‌های ابزار دقیقاً تحت هویت OAuth تماس‌گیرنده اصالت‌سنجی‌شده اجرا می‌شوند.
• حذف --allow-unauthenticated، زیرساخت Cloud Run‏ IAM را اعمال می‌کند، که تماس‌گیرندگان را ملزم می‌کند با هر درخواست، نشان‌های هویت Google Cloud OIDC را ارسال کنند. ازآنجایی‌که کارخواه‌های هوش مصنوعی استاندارد (مانند Claude و ChatGPT) بااستفاده از OAuth کاربر نهایی اصالت‌سنجی می‌کنند و نه بااستفاده از کدهای شناسه Google Cloud IAM، اتصال‌های مستقیم از این پلاتفرم‌ها به --allow-unauthenticated با OAuth سطح برنامه نیاز دارند.

پیکربندی کارخواه MCP

پس‌از استقرار، مشتری MCP خود را با نشانی وب Cloud Run پیکربندی کنید. چون سرور به اصالت‌سنجی OAuth 2.0 نیاز دارد، کارخواه باید از جریان MCP OAuth پشتیبانی کند یا یک رمزیاب دارنده مجاز ارائه دهد:

• کارخواه‌های فعال‌شده با OAuth: برای کارخواه‌هایی که از MCP OAuth discovery پشتیبانی می‌کنند (مثل Antigravity)، اتصال به نقطه پایانی باعث فعال شدن پیام‌واره اصالت‌سنجی برای ورود به سیستم با Google و اعطای دامنه https://www.googleapis.com/auth/adwords (فهرست‌شده به‌عنوان .../auth/adwords در کنسول Google Cloud) می‌شود.
• پلاتفرم‌های هوش مصنوعی طرف سوم (Claude،‏ ChatGPT): در تنظیمات یکپارچه‌سازی یا اتصال‌دهنده کارخواه، اتصال‌دهنده سفارشی‌ای اضافه کنید که به نشانی وب 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 Unauthorized (غیرمجاز) دریافت خواهند کرد. برای این ابزارها، درعوض از پیکربندی 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

مراحل بعدی

• نصب مهارت‌های نماینده Google Ads API
• با «دستیار توسعه‌دهنده Google Ads API» آشنا شوید
• نصب و استفاده از «دستیار توسعه‌دهنده Google Ads API»