پروتکل بافتار مدل (MCP) یک استاندارد باز است که به مدل‌های زبانی بزرگ (LLM) امکان می‌دهد به‌طور ایمن با داده‌ها و برنامه‌های خارجی تعامل داشته باشند. سرور Google Ads MCP پلی استاندارد برای Google Ads API فراهم می‌کند که به عامل‌های هوشواره امکان می‌دهد بااستفاده از زبان طبیعی داده‌های پویش را تجزیه‌وتحلیل و بازیابی کنند.
منابع و پشتیبانی انجمن
مخزن GitHub: در مخزن google-ads-mcp، نسخه‌های نمایشی و نمونه‌ها را پیدا کنید، اشکال‌ها را گزارش کنید، یا ویژگی پیشنهاد دهید.
از برگه «مشکلات» برای گزارش اشکال و درخواست ویژگی استفاده کنید.
انجمن: به کانال
#ads-api-ai-toolsدر Google Advertising Community Discord بپیوندید.
نمای کلی فنی
با پیاده‌سازی این سرور MCP، دیگر نیازی به نوشتن «کد چسبنده» سفارشی برای اصالت‌سنجی «میانای برنامه‌سازی کاربردی Google Ads»، واکشی منبع، و تجزیه داده‌ها نخواهید داشت. کارساز ابزارهای خاصی را آشکار می‌کند که یک مدل زبانی بزرگ می‌تواند به‌طور خودکار آن‌ها را کشف و فراخوانی کند.
مشخصات کلیدی
- پروتکل: MCP (پروتکل زمینه‌ای مدل)
- حالت: فقط خواندنی (نسخه کنونی)
- زبان: Python
- انتقال: ورودی/خروجی استاندارد (
stdio) یا HTTP جاری‌سازی‌شدنی (streamable-http/ Cloud Run) - اصالت‌سنجی: OAuth 2.0 یا حساب سرویس
نحوه عملکرد حلقه تعامل
- درخواست: کاربر پُرسمانی مانند «عملکرد پویش من در این هفته چگونه است؟» ارسال می‌کند.
- اکتشاف: «مدل زبانی بزرگ» ابزارهای دردسترس خود را بررسی می‌کند و قابلیت‌های جستجوی
google-ads-mcpرا شناسایی می‌کند. - اجرا: سرور MCP منطق زیربنایی Python را برای پُرسمان کردن «میانای برنامه‌سازی کاربردی Google Ads» اجرا می‌کند.
- تزریق بافت: نتایج ساختاری به پنجره بافت LLM برگردانده می‌شود.
- پاسخ: مدل زبانی بزرگ داده‌ها را در قالب پاسخی قابل‌خواندن برای انسان ترکیب می‌کند.
شروع کنید
برای پیکربندی و استفاده از سرور Google Ads MCP، این مراحل را دنبال کنید.
پیش‌نیازها
قبل‌از پیکربندی، مطمئن شوید که اطلاعات اعتباری زیر را از کنسول 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 را به فایل 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 یا در هر زیرساخت مبتنی بر فضای ابری دیگری میزبانی کنید. این کار زمانی مفید است که بخواهید سرور را بین کارگزاران مختلف هم‌رسانی کنید یا آن را به‌عنوان سرویس وب اجرا کنید.
پیش‌نیازها
- پروژه Google Cloud.
ابزار خط فرمان
gcloudنصب شده، اصالت‌سنجی شده، و با پروژه فعال پیکربندی شده باشد:gcloud config set project YOUR_PROJECT_ID
ساختن و ارسال تصویر Docker
می‌توانید از Cloud Build برای ساختن و انتقال تصویر به Artifact Registry بدون نیاز به نصب محلی Docker استفاده کنید.
ایجاد مخزن در Artifact Registry:
gcloud artifacts repositories create mcp-servers \ --repository-format=docker --location=us-central1به فهرست راهنمای پروژه بروید:
cd <full path>/google-ads-mcpتصویر را بسازید و ارسال کنید:
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 در سطح برنامه. مطمئن شوید که:- نشانی‌های وب هدایت مجاز مناسب را برای هر مشتری هوش مصنوعی که قصد اتصال آن را دارید (مانند
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» و «رمز کارخواه» خودتان) انتخاب کنید، و مطمئن شوید نشانی وب تماس برگشتی مشتری به نشانی‌های وب هدایت مجاز کارخواه OAuth شما اضافه شده است. (شرکت‌کنندگان فهرست مجاز در نسخه آزمایشی نقطه پایانی میزبانی‌شده نیز می‌توانند به راهنمای راه‌اندازی MCP میزبانی‌شده مراجعه کنند.) - کارخواه‌های بدون پشتیبانی OAuth: کارخواه‌هایی که از جریان‌های HTTP OAuth پشتیبانی نمی‌کنند، پاسخ HTTP 401 Unauthorized (غیرمجاز) دریافت خواهند کرد. برای این ابزارها، درعوض از پیکربندی stdio محلی استفاده کنید.
پیکربندی نمونه برای کارخواه OAuth-capable (برای نمونه،
~/.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 (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