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

Model Context Protocol (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 شما که دارای سطوح دسترسی مناسب به API است.
• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: شناسه کارخواه OAuth 2.0 (پیکربندی‌شده به‌عنوان برنامه وب در پروژه Google Cloud شما) برای اصالت‌سنجی OAuth در سطح برنامه. مطمئن شوید:
  • شناسه‌های URI هدایت مجاز مناسب را برای هر مشتری هوش مصنوعی که قصد اتصال آن را دارید (مانند 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، اتصال‌های مستقیم از این پلاتفرم‌ها به --allow-unauthenticated با OAuth سطح برنامه نیاز دارد.

احتیاط: هرگز GOOGLE_ADS_MCP_OAUTH_CLIENT_ID و GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET را هنگام استقرار با --allow-unauthenticated حذف نکنید. این متغیرهای محیطی سرور را فعال می‌کنند تا از حالت محلی stdio به انتقال streamable-http تغییر کند. بدون آن‌ها، سرور نمی‌تواند اصالت‌سنجی را اعمال کند و به «اعتبارنامه‌های پیش‌فرض برنامه» (ADC) برمی‌گردد و اعتبارنامه‌های حساب سرویس محفظه را درمعرض تماس‌گیرندگان اصالت‌سنجی‌نشده قرار می‌دهد.

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

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

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

  این برای درک ساختار داده‌ها و اینکه چه فیلدهایی برای پُرسمان دردسترس هستند مفید است.

توجه: این پیاده‌سازی صرفاً خواندنی است. نمی‌تواند پیشنهاد قیمت‌ها را تغییر دهد، پویش‌ها را موقتاً متوقف کند، یا دارایی‌های جدید ایجاد کند. برای تولید کد کتابخانه کارخواه برای عملیات‌های تغییر، اعتبارسنجی محلی پُرسمان‌های GAQL، یا بازرسی طرح‌واره‌های Protobuf، از دستیار توسعه‌دهنده Google Ads API استفاده کنید. برای راه‌اندازی MCP با راهنمایی و گردش کار تشخیص حساب، مهارت‌های عامل Google Ads API را نصب کنید.

پیام‌واره‌های نمونه برای شروع

بپرسید سرور چه کاری می‌تواند انجام دهد:

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 Developer Assistant