Google Ads एमसीपी सर्वर: डेवलपर इंटिग्रेशन गाइड

मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) एक ओपन स्टैंडर्ड है. इसकी मदद से, लार्ज लैंग्वेज मॉडल (एलएलएम), बाहरी डेटा और ऐप्लिकेशन के साथ सुरक्षित तरीके से इंटरैक्ट कर सकते हैं. Google Ads का एमसीपी सर्वर, Google Ads API के लिए एक स्टैंडर्ड ब्रिज उपलब्ध कराता है. इससे एआई एजेंट, खाते में मौजूद डेटा को वापस पा सकते हैं और उसका विश्लेषण कर सकते हैं. साथ ही, नैचुरल लैंग्वेज का इस्तेमाल करके, ऐसेट बना सकते हैं, वीडियो अपलोड कर सकते हैं, और लेबल मैनेज कर सकते हैं.

कम्यूनिटी के संसाधन और सहायता

  • GitHub रिपॉज़िटरी: google-ads-mcp रिपॉज़िटरी में डेमो और उदाहरण देखें, गड़बड़ियों की शिकायत करें या सुविधाओं के सुझाव दें.

    गड़बड़ी की रिपोर्ट करने और सुविधा का अनुरोध करने के लिए, समस्याएं टैब का इस्तेमाल करें.

  • कम्यूनिटी: Google Advertising Community Discord पर #ads-api-ai-tools चैनल में शामिल हों.

तकनीकी जानकारी

Google Ads MCP सर्वर को इंटिग्रेट करने से, Google Ads API की पुष्टि करने, संसाधन फ़ेच करने, डेटा पार्स करने, और ऐसेट या लेबल में बदलाव करने के लिए कस्टम कोड लिखने की ज़रूरत नहीं पड़ती. सर्वर, कॉल किए जा सकने वाले टूल और रेफ़रंस संसाधन (मुख्य सुविधाएं देखें) दिखाता है. एलएलएम, इनकी जांच कर सकता है और इन्हें कॉल कर सकता है.

मुख्य विशेषताएं

  • प्रोटोकॉल: एमसीपी (मॉडल कॉन्टेक्स्ट प्रोटोकॉल)
  • मोड: रीड और पार्शियल म्यूटेट (ऐसेट बनाना, वीडियो अपलोड करना, और लेबल मैनेज करना. इसके लिए, सुझाव और पुष्टि करने की सुविधा या कॉन्फ़िगर किए जा सकने वाले सिर्फ़ पढ़ने वाला मोड का इस्तेमाल किया जा सकता है)
  • भाषा: Python 3.10 या इसके बाद का वर्शन
  • ट्रांसपोर्ट: स्टैंडर्ड इनपुट/आउटपुट (stdio) या स्ट्रीम किया जा सकने वाला एचटीटीपी (Cloud Run पर streamable-http)
  • पुष्टि करना: लोकल stdio के लिए, ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल (OAuth 2.0 उपयोगकर्ता क्रेडेंशियल या सेवा खाता) या रिमोट एचटीटीपी के लिए, OAuth 2.0 वेब ऐप्लिकेशन क्रेडेंशियल

इंटरैक्शन लूप कैसे काम करता है

  1. अनुरोध: आपको कोई प्रॉम्प्ट सबमिट करना होगा. जैसे, "इस हफ़्ते मेरे कैंपेन की परफ़ॉर्मेंस कैसी है?" या "हमारी समर सेल के लिए कॉलआउट ऐसेट बनाएं".
  2. खोजना: एलएलएम, उपलब्ध टूल और संसाधनों की जांच करता है और क्वेरी से मैच करने वाला google-ads-mcp टूल चुनता है.
  3. एग्ज़ीक्यूशन या ड्राई-रन वैलिडेशन: रीड टूल, सीधे Google Ads API से क्वेरी करते हैं. म्यूटेट टूल, पहले प्रपोज़ मोड (validate_only=True) में चलाए जाते हैं, ताकि बदलावों को लागू किए बिना इनपुट की पुष्टि की जा सके. इसके बारे में ज़्यादा जानने के लिए, सुझाव देने और पुष्टि करने की सुरक्षा से जुड़ा वर्कफ़्लो देखें.
  4. कॉन्टेक्स्ट इंजेक्शन: एमसीपी सर्वर, एलएलएम की कॉन्टेक्स्ट विंडो में स्ट्रक्चर्ड क्वेरी के नतीजे दिखाता है. इसके अलावा, यह सुझाई गई change_items एंट्री और पुष्टि करने के लिए checksum डाइजेस्ट दिखाता है.
  5. जवाब और पुष्टि: एलएलएम आपको जवाब देता है या सुझाए गए बदलावों की पुष्टि करने के लिए कहता है. आपकी अनुमति मिलने के बाद, एलएलएम बदलाव करने के लिए, validate_only=False और मैच होने वाली checksum वैल्यू के साथ, म्यूटेट टूल को फिर से कॉल करता है.

अपनी प्रोफ़ाइल बनाना शुरू करें

Google Ads एमसीपी सर्वर को स्थानीय तौर पर कॉन्फ़िगर करने और चलाने के लिए, यह तरीका अपनाएं. इसके बजाय, शेयर की गई रिमोट सेवा को डिप्लॉय करने के लिए, Google Cloud पर डिप्लॉयमेंट देखें.

ज़रूरी शर्तें

सर्वर को कॉन्फ़िगर करने से पहले, अपने लोकल एनवायरमेंट और Google Cloud Console में ये ज़रूरी शर्तें पूरी करें:

  • Google Cloud प्रोजेक्ट: Google Ads API की सुविधा वाला कोई Google Cloud प्रोजेक्ट बनाएं या चुनें. एपीआई को चालू करने पर, टेस्ट खातों के लिए, रीड और म्यूटेट वर्कफ़्लो की जांच करने के लिए टेस्ट ऐक्सेस मिलता है. प्रोडक्शन खातों को ऐक्सेस करने के लिए, Google Ads API के खास जानकारी वाले पेज पर जाकर, एक्सप्लोरर, बेसिक या स्टैंडर्ड ऐक्सेस की जांच करें या इनमें से किसी एक ऐक्सेस लेवल के लिए आवेदन करें. ऐसा न होने पर, प्रोडक्शन कॉल AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION गड़बड़ी के साथ फ़ेल हो जाते हैं. Google, 9 सितंबर, 2026 को डेवलपर टोकन (GOOGLE_ADS_DEVELOPER_TOKEN) बंद कर देगा. आपके OAuth क्लाइंट या सेवा खाते का मालिकाना हक रखने वाला Google क्लाउड प्रोजेक्ट, आपके एपीआई ऐक्सेस लेवल को तय करता है.
  • क्रेडेंशियल: लोकल stdio मोड, आपके क्लाउड प्रोजेक्ट में मौजूद OAuth 2.0 क्लाइंट सीक्रेट JSON फ़ाइल या सेवा खाते से, ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल (एडीसी) की मदद से पुष्टि करता है. जब आपको अपना डिफ़ॉल्ट कोटा या एडीसी प्रोजेक्ट तय करना हो, तब GOOGLE_CLOUD_PROJECT एनवायरमेंट वैरिएबल सेट करें. रिमोट streamable-http डिप्लॉयमेंट के लिए, OAuth 2.0 वेब ऐप्लिकेशन क्लाइंट आईडी और क्लाइंट सीक्रेट की ज़रूरत होती है. ज़्यादा जानकारी के लिए, Google Cloud Run पर डिप्लॉय करना लेख पढ़ें.
  • लोकल सॉफ़्टवेयर (stdio मोड के लिए): Python 3.10 या इसके बाद का वर्शन, pipx, और gcloud कमांड-लाइन टूल इंस्टॉल करें. इसका इस्तेमाल, उपयोगकर्ता की एडीसी फ़ाइलें जनरेट करने के लिए किया जाता है.

कॉन्फ़िगरेशन

  1. एपीआई की सुविधा वाले Google Cloud प्रोजेक्ट के OAuth क्लाइंट का इस्तेमाल करके, ऐप्लिकेशन डिफ़ॉल्ट क्रेडेंशियल (एडीसी) जनरेट करें. साथ ही, Google Ads API का दायरा शामिल करें:

    gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=PATH_TO_CLIENT_SECRET_JSON

    इनकी जगह ये डालें:

    • PATH_TO_CLIENT_SECRET_JSON: आपके OAuth 2.0 क्लाइंट सीक्रेट की JSON फ़ाइल का पाथ.

    यह कमांड Credentials saved to file: [PATH_TO_CREDENTIALS_JSON] को प्रिंट करता है (जैसे, Linux और macOS पर ~/.config/gcloud/application_default_credentials.json). इसके बजाय, सेवा खाते से पुष्टि करने के लिए, यह चरण छोड़ें और GOOGLE_APPLICATION_CREDENTIALS को अपनी सेवा खाते की कुंजी वाली JSON फ़ाइल पर ले जाएं या --impersonate-service-account को gcloud auth application-default login पर पास करें.

  2. सर्वर को अपने होस्ट की एमसीपी कॉन्फ़िगरेशन फ़ाइल (जैसे, ~/.gemini/config/mcp_config.json, ~/.gemini/settings.json या ~/.claude/settings.json) में जोड़ें:

    {
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "google-ads-mcp==0.0.6",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "PROJECT_ID",
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON"
      }
    }
  }
}

    इनकी जगह ये डालें:

    • PROJECT_ID: आपका Google Cloud प्रोजेक्ट आईडी.
    • PATH_TO_CREDENTIALS_JSON: पहले चरण में प्रिंट की गई एडीसी JSON फ़ाइल का पाथ या आपके सेवा खाते की कुंजी वाली JSON फ़ाइल का पाथ. डिफ़ॉल्ट gcloud एडीसी फ़ाइल लोकेशन का इस्तेमाल करते समय, GOOGLE_APPLICATION_CREDENTIALS को छोड़ा जा सकता है.

    मैनेजर खाते से क्लाइंट खातों को ऐक्सेस करने के लिए, env में GOOGLE_ADS_LOGIN_CUSTOMER_ID (बिना हाइफ़न के 10 अंक) सेट करें या अलग-अलग टूल कॉल पर login_customer_id पैरामीटर पास करें.

ज़रूरी नहीं: अपने एजेंट को स्किल और डेवलपर असिस्टेंट से लैस करना

Google Ads का एमसीपी सर्वर, आपके एआई क्लाइंट को खाते के रिपोर्टिंग डेटा का लाइव ऐक्सेस देता है. साथ ही, ऐसेट बनाने, वीडियो अपलोड करने, और लेबल मैनेज करने वाले टूल का ऐक्सेस भी देता है. एमसीपी सर्वर को इन साथी टूल के साथ जोड़ें, ताकि आपके एजेंट को मान्य Google Ads क्वेरी लैंग्वेज (GAQL) क्वेरी बनाने और खाते की परफ़ॉर्मेंस में होने वाले बदलावों का विश्लेषण करने में मदद मिल सके. ये टूल, क्लाइंट लाइब्रेरी कोड भी जनरेट करते हैं. जैसे, बनाई गई ऐसेट को कैंपेन से लिंक करने या काम न करने वाले अन्य म्यूटेशन करने के लिए स्क्रिप्ट:

  • Google Ads API एजेंट की स्किल: पोर्टेबल वर्कफ़्लो मॉड्यूल (इनमें google-ads-api-mcp-setup, google-ads-api-account-diagnostics, और google-ads-api-quickstart शामिल हैं), जो आपके एजेंट को कम टोकन ओवरहेड के साथ Google Ads एमसीपी सर्वर का इस्तेमाल करने में मदद करते हैं. इन्हें इंस्टॉल करने के लिए, यह कमांड चलाएं (इसके लिए Node.js ज़रूरी है) या Antigravity, Claude Code, Codex, और Cursor सेटअप के लिए, Google Ads API एजेंट स्किल गाइड देखें:

    npx skills add google/skills/skills/ads

  • Google Ads API Developer Assistant: यह Google Antigravity और Claude Code के लिए एक मॉड्यूलर प्लग इन है. यह लोकल Protobuf स्कीमा की जांच, GAQL की पुष्टि, क्लाइंट लाइब्रेरी कोड जनरेशन, और ऑफ़लाइन कन्वर्ज़न से जुड़ी समस्या हल करने की सुविधा देता है. Google Ads API डेवलपर असिस्टेंट क्या है? लेख पढ़ें या इंस्टॉल करने का तरीका बताने वाली गाइड देखें.

मुख्य सुविधाएं

यहां दिए गए सेक्शन में, सर्वर के रीड टूल, पार्शियल म्यूटेट टूल, और रेफ़रंस रिसॉर्स के बारे में बताया गया है. v0.0.6 से, टूल डिफ़ॉल्ट रूप से अपनी कैटगरी के नेमस्पेस प्रीफ़िक्स (जैसे, search_search) के साथ रजिस्टर होते हैं. प्रीफ़िक्स के बिना रिलीज़ किए गए वर्शन से प्रॉम्प्ट या अनुमति वाली सूचियों को अपग्रेड करते समय, टूल के नाम अपडेट करें या tools_config.yaml में खाली प्रीफ़िक्स ("") सेट करें. इसके बारे में ज़्यादा जानने के लिए, टूल के नेमस्पेस और सिर्फ़ पढ़ने वाले मोड को कॉन्फ़िगर करना लेख पढ़ें.

रीड टूल

  • customers_list_accessible_customers (टूल list_accessible_customers): यह टूल, उन Google Ads ग्राहक आईडी को दिखाता है जिन्हें प्रमाणित उपयोगकर्ता सीधे ऐक्सेस कर सकता है.
  • search_search (टूल search): यह रॉ GAQL स्ट्रिंग के बजाय, स्ट्रक्चर्ड पैरामीटर (customer_id, resource, और fields के साथ-साथ वैकल्पिक conditions, orderings, limit, और login_customer_id) से GAQL SearchStream क्वेरी बनाता है और उन्हें चलाता है. हर क्वेरी में PARAMETERS omit_unselected_resource_names=true को जोड़ा जाता है, ताकि संसाधन के एट्रिब्यूट, मेट्रिक, सेगमेंट, बजट, और स्टेटस को साफ़ तौर पर फ़ेच किया जा सके.
  • metadata_get_resource_metadata (टूल get_resource_metadata): यह Google Ads API के रिसॉर्स टाइप (उदाहरण के लिए, "campaign") के लिए, चुने जा सकने वाले, फ़िल्टर किए जा सकने वाले, और क्रम से लगाए जा सकने वाले एट्रिब्यूट, मेट्रिक, और सेगमेंट को वापस लाता है. इस मेटाडेटा का इस्तेमाल करके, मान्य क्वेरी फ़ील्ड खोजें. इनमें v26.2 जैसे छोटे रिलीज़ में जोड़ी गई मेट्रिक और सेगमेंट शामिल हैं. इसके बाद, search_search टूल को कॉल करें.

बदलाव करने वाले टूल (कुछ ही सुविधाएं काम करती हैं)

  • assets_create_asset (टूल create_asset): यह Google Ads की ऐसेट को अलग से बनाता है. इसके लिए, TEXT, IMAGE, YOUTUBE_VIDEO, SITELINK, CALLOUT, और STRUCTURED_SNIPPET ऐसेट टाइप के लिए खास पैरामीटर का इस्तेमाल किया जाता है. बदले जा सकने वाले अन्य AssetService टाइप (जैसे, PRICE, PROMOTION, CALL या BUSINESS_MESSAGE) के लिए, extra_params डिक्शनरी पास करें. साथ ही, SITELINK ऐसेट के लिए, sitelink_link_text के साथ रूट-लेवल final_urls शामिल करें. लोकल फ़ाइल पाथ (image_asset_path) सिर्फ़ लोकल stdio मोड में काम करते हैं. रिमोट एचटीटीपी डिप्लॉयमेंट के लिए, base64-encoded image_asset_data पैरामीटर को पास करें. साथ ही, image_asset_mime_type को IMAGE_PNG, IMAGE_JPEG या IMAGE_GIF (20 एमबी तक) पर सेट करें.
  • assets_upload_video_asset (टूल upload_video_asset): यह टूल, Google Ads API के ज़रिए YouTube पर लोकल वीडियो फ़ाइल अपलोड करता है (.3gp, .avi, .flv, .mkv, .mov, .mp4, .mpeg, .mpg, .ogg, .webm या .wmv). हालांकि, ऐसा सिर्फ़ लोकल stdio मोड में किया जा सकता है. video_title और video_description, दोनों ज़रूरी पैरामीटर हैं. साथ ही, निजता सेटिंग डिफ़ॉल्ट रूप से UNLISTED पर सेट होती है. इसके अलावा, विज्ञापन देने वाले व्यक्ति या कंपनी के मालिकाना हक वाले ब्रैंड चैनलों पर, उपयोगकर्ता के OAuth के साथ यह सेटिंग PUBLIC पर सेट होती है. यह टूल, Google Ads video_upload_id वैल्यू (और संसाधन का नाम) दिखाता है, न कि 11 वर्णों वाला YouTube video_id. search_search टूल (you_tube_video_upload.video_upload_id के हिसाब से फ़िल्टर किया गया) की मदद से, you_tube_video_upload क्वेरी के लिए you_tube_video_upload.state = 'PROCESSED' तक. इसके बाद, you_tube_video_upload.video_id को youtube_video_id पैरामीटर के तौर पर assets_create_asset (asset_type="YOUTUBE_VIDEO") को पास करें.
  • labels_manage_labels (टूल manage_labels): यह टूल, खाते के लेबल बनाता है, उन्हें अपडेट करता है, और हटाता है. इसमें नाम, ब्यौरा, और हेक्स बैकग्राउंड का रंग शामिल है.
  • labels_manage_label_associations (टूल manage_label_associations): CAMPAIGN, CUSTOMER, AD_GROUP, और AD_GROUP_CRITERION संसाधनों पर, CREATE और REMOVE लेबल असोसिएशन ऑपरेशन काम करते हैं. हालांकि, UPDATE काम नहीं करता. CUSTOMER संसाधनों के लिए, resource_id ज़रूरी नहीं है और यह डिफ़ॉल्ट रूप से customer_id पर सेट होता है. AD_GROUP_CRITERION संसाधनों के लिए, कंपोज़िट {ad_group_id}~{criterion_id} आईडी पास करें. साथ ही, resource_id और label_id या association_resource_name को पास करके असोसिएशन हटाएं. विज्ञापन-लेवल पर AD_GROUP_AD लेबल इस्तेमाल नहीं किए जा सकते.

रेफ़रंस के तौर पर इस्तेमाल किए जाने वाले संसाधन

सर्वर, सिर्फ़ पढ़ने के लिए उपलब्ध चार एमसीपी संसाधनों को दिखाता है. ये संसाधन, आपकी tools_config.yaml सेटिंग के बावजूद माउंट रहते हैं:

  • resource://discovery-document: Google Ads API के संसाधनों, सेवा के तरीकों, और स्कीमा की JSON REST डिस्कवरी की खास जानकारी. यह metadata_get_resource_metadata टूल के साथ काम करता है. यह टूल, GAQL क्वेरी के ऐसे फ़ील्ड दिखाता है जिन्हें चुना जा सकता है, फ़िल्टर किया जा सकता है, और क्रम से लगाया जा सकता है.
  • resource://metrics: Google Ads API की मेट्रिक के लिए एचटीएमएल रेफ़रंस दस्तावेज़.
  • resource://segments: Google Ads API सेगमेंट के लिए एचटीएमएल रेफ़रंस दस्तावेज़.
  • resource://release-notes: एचटीएमएल Google Ads API के रिलीज़ नोट, जिनमें वर्शन में हुए बदलावों और नई सुविधाओं के बारे में बताया गया है.

सुरक्षा से जुड़ा वर्कफ़्लो, जिसमें सुझाव देने और पुष्टि करने की सुविधा शामिल है

हर म्यूटेट टूल (assets_create_asset, assets_upload_video_asset, labels_manage_labels, और labels_manage_label_associations), दो चरणों वाले सुझाव और पुष्टि वर्कफ़्लो को लागू करता है. इससे खाते में अनचाहे बदलावों को रोकने में मदद मिलती है:

  1. Propose (validate_only=True, डिफ़ॉल्ट): यह बदलावों को लागू किए बिना, इनपुट की पुष्टि करता है. ऐसेट और लेबल टूल, लाइव Google Ads API validate_only ड्राई रन को लागू करते हैं. YouTubeVideoUploadService में ड्राई-रन मोड नहीं होता है. इसलिए, assets_upload_video_asset लोकल फ़ाइल की पुष्टि करता है और उसके साइज़ और बदलाव के टाइमस्टैंप को बाइंड करता है. हर टूल, किसी व्यक्ति के लिए आसानी से पढ़ा जा सकने वाला डेटा change_items एंट्री और स्टेटलेस SHA-256 checksum डाइजेस्ट दिखाता है. यह डाइजेस्ट, customer_id पैरामीटर और अनुरोध के पेलोड से जुड़ा होता है.
  2. पुष्टि करना (validate_only=False): change_items सूची दिखाने और आपकी अनुमति मिलने के बाद, एजेंट टूल को फिर से कॉल करता है. इसके लिए, वह validate_only=False, एक जैसे customer_id पैरामीटर और आर्ग्युमेंट, और पहले चरण की checksum वैल्यू का इस्तेमाल करता है. खाते में बदलाव करने से पहले, सर्वर किसी भी ऐसे चेकसम को अस्वीकार कर देता है जो मौजूद नहीं है या मेल नहीं खाता.

टूल के नेमस्पेस और सिर्फ़ पढ़ने वाले मोड को कॉन्फ़िगर करना

सर्वर, डिफ़ॉल्ट tools_config.yaml फ़ाइल को टूल की सभी पांच कैटगरी (customers, search, metadata, labels, और assets) के साथ बंडल करता है. tools_config.yaml को पसंद के मुताबिक बनाएं, ताकि अलग-अलग टूल या नेमस्पेस को चुनिंदा तौर पर चालू या बंद किया जा सके. साथ ही, नेमस्पेस के प्रीफ़िक्स बदले या हटाए जा सकें या सिर्फ़ पढ़ने के लिए डिप्लॉयमेंट लागू किया जा सके.

स्टार्टअप के दौरान, सर्वर tools_config.yaml को इस क्रम में रिज़ॉल्व करता है:

  1. GOOGLE_ADS_MCP_TOOLS_CONFIG एनवायरमेंट वैरिएबल में साफ़ तौर पर बताया गया पाथ (लोकल stdio होस्ट के लिए सुझाया गया है, जिनकी वर्किंग डायरेक्ट्री आपके प्रोजेक्ट फ़ोल्डर से अलग हो सकती है).
  2. सर्वर की मौजूदा वर्किंग डायरेक्ट्री में मौजूद tools_config.yaml फ़ाइल.
  3. पैकेज के साथ बंडल की गई डिफ़ॉल्ट tools_config.yaml फ़ाइल.

अगर GOOGLE_ADS_MCP_TOOLS_CONFIG किसी ऐसी फ़ाइल पर ले जाता है जो मौजूद नहीं है या अगर कोई रिज़ॉल्व की गई कॉन्फ़िगरेशन फ़ाइल अमान्य है, तो सर्वर डिफ़ॉल्ट पर वापस जाने के बजाय, स्टार्टअप के समय गड़बड़ी का मैसेज दिखाता है.

tools_config.yaml फ़ाइल में मौजूद यह कोड, डिप्लॉयमेंट को सिर्फ़ पढ़ने के लिए सेट करता है:

namespaces:
  customers: true
  search: true
  metadata: true
  labels: false
  assets: false

यहां दी गई tools_config.yaml फ़ाइल, प्रीफ़िक्स को पसंद के मुताबिक बनाती है और अलग-अलग टूल को फ़िल्टर करती है. उदाहरण के लिए, Cloud Run पर base64 create_asset टूल को एक्सपोज़ करना और सिर्फ़ लोकल upload_video_asset टूल को बंद करना:

namespaces:
  # Default prefix ("customers_list_accessible_customers")
  customers: true

  # Empty prefix mounts unprefixed tool names ("search")
  search: ""

  # Custom prefix ("schema_get_resource_metadata")
  metadata: "schema"

  # Enable only specific tools in a multi-tool category
  assets:
    enabled_tools:
      - create_asset

शुरू करने के लिए प्रॉम्प्ट के सैंपल

सर्वर से कनेक्ट करने के बाद, अपने एमसीपी क्लाइंट में ये प्रॉम्प्ट आज़माएँ.

सर्वर से पूछें कि वह क्या कर सकता है

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

ऐसेट बनाना, वीडियो अपलोड करना, और लेबल मैनेज करना

Create a callout asset with the text "Free Shipping" for account 1234567890

Upload /path/to/promo.mp4 with title "Summer Sale" and description "Summer promo video" for account 1234567890

Create a label named "Q4 Promo" with background color #34A853 and apply it to campaign 9876543210 in account 1234567890

Google Cloud पर डिप्लॉयमेंट

एमसीपी सर्वर को कई एजेंट के साथ शेयर करने या उसे वेब सेवा के तौर पर चलाने के लिए, उसे स्थानीय तौर पर चलाने के बजाय, Google Cloud Run या क्लाउड इन्फ़्रास्ट्रक्चर की सेवा देने वाली किसी अन्य कंपनी पर होस्ट करें.

ज़रूरी शर्तें

  1. Google Ads API की सुविधा वाला Google Cloud प्रोजेक्ट. प्रोडक्शन टेस्टिंग ट्रैक का ऐक्सेस पाने की ज़रूरी शर्तों के लिए, ज़रूरी शर्तें देखें.

  2. gcloud कमांड-लाइन टूल इंस्टॉल किया गया हो, उसकी पुष्टि की गई हो, और उसे किसी चालू प्रोजेक्ट के साथ कॉन्फ़िगर किया गया हो:

    gcloud config set project PROJECT_ID

    इनकी जगह ये डालें:

    • PROJECT_ID: आपका Google Cloud प्रोजेक्ट आईडी.

डॉकर इमेज बनाना और उसे पुश करना

Docker को स्थानीय तौर पर इंस्टॉल किए बिना, कंटेनर इमेज बनाने और उसे Artifact Registry में पुश करने के लिए, Cloud Build का इस्तेमाल करें:

  1. Artifact Registry में डेटाबेस बनाएं:

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

  2. GitHub रिपॉज़िटरी में रिलीज़ टैग से इमेज बनाएं और सबमिट करें (या अगर आपने Dockerfile या tools_config.yaml को पसंद के मुताबिक बनाया है, तो लोकल चेकआउट में . से):

    gcloud builds submit https://github.com/googleads/google-ads-mcp \
  --git-source-revision=v0.0.6 \
  --tag=us-central1-docker.pkg.dev/PROJECT_ID/mcp-servers/google-ads-mcp:v0.0.6

    इनकी जगह ये डालें:

    • PROJECT_ID: आपका Google Cloud प्रोजेक्ट आईडी.

    जब भी Google Ads API के नए वर्शन (जैसे, v26.2) के लिए, बंडल की गई google-ads Python क्लाइंट लाइब्रेरी को अपग्रेड या google-ads-mcp को अपडेट किया जाए, तब इमेज को फिर से बनाएं और फिर से डिप्लॉय करें.

Google Cloud Run पर डिप्लॉय करें

अपनी Cloud Run सेवा के लिए, यहां दिए गए एनवायरमेंट वैरिएबल और सीक्रेट कॉन्फ़िगर करें:

  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: ऐप्लिकेशन-लेवल पर OAuth की मदद से पुष्टि करने के लिए, एपीआई की सुविधा वाले Google Cloud प्रोजेक्ट से OAuth 2.0 वेब ऐप्लिकेशन का क्लाइंट आईडी. OAuth कॉन्फ़िगरेशन के लिए, यह तरीका अपनाएं:
    • आपको जिन एआई क्लाइंट को कनेक्ट करना है उनके लिए, अनुमति वाले रीडायरेक्ट यूआरआई जोड़ें. जैसे, https://claude.ai/api/mcp/auth_callback, https://chatgpt.com/connector_platform_oauth_redirect या https://antigravity.google/oauth-callback.
    • एपीआई और सेवाएं > OAuth की सहमति वाली स्क्रीन > डेटा ऐक्सेस (दायरे जोड़ें या हटाएं) में जाकर, OAuth की सहमति वाली स्क्रीन पर https://www.googleapis.com/auth/adwords दायरा जोड़ें.
    • अगर OAuth के लिए सहमति वाली स्क्रीन की पब्लिशिंग स्थिति टेस्टिंग (डिफ़ॉल्ट) पर सेट है, तो एमसीपी सर्वर से कनेक्ट करने वाले Google खातों को एपीआई और सेवाएं > OAuth के लिए सहमति वाली स्क्रीन > ऑडियंस (टेस्ट उपयोगकर्ता > + उपयोगकर्ता जोड़ें) में जाकर, टेस्ट उपयोगकर्ता के तौर पर जोड़ें.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: आपके OAuth क्लाइंट आईडी से जुड़ा OAuth क्लाइंट सीक्रेट.
  • GOOGLE_ADS_MCP_BASE_URL: आपके एमसीपी सर्वर का सार्वजनिक बेस यूआरएल (उदाहरण के लिए, https://google-ads-mcp-xyz-uc.a.run.app). Cloud Run, शुरुआती डिप्लॉयमेंट के दौरान यह यूआरएल असाइन करता है. इसलिए, पहले इस वैरिएबल के बिना डिप्लॉय करें और बाद में सेवा को अपडेट करें.
  • GOOGLE_ADS_MCP_JWT_SIGNING_KEY (एक से ज़्यादा इंस्टेंस Cloud Run के लिए सुझाया गया): यह एक स्थायी सीक्रेट है, जो कंटेनर के रीस्टार्ट होने और हॉरिज़ॉन्टल स्केलिंग के दौरान, FastMCP JWTs पर हस्ताक्षर करता है.
  • GOOGLE_ADS_MCP_STORAGE_TYPE (एक से ज़्यादा इंस्टेंस Cloud Run के लिए सुझाया गया है): OAuth क्लाइंट रजिस्ट्रेशन और टोकन के लिए पर्सिस्टेंट बैकएंड (redis के साथ GOOGLE_ADS_MCP_STORAGE_REDIS_URL या firestore). स्टॉक v0.0.6 Dockerfile सिर्फ़ इन-मेमोरी बैकएंड इंस्टॉल करता है. इसलिए, पहले कस्टम Dockerfile में py-key-value-aio[redis] या .[firestore] इंस्टॉल करें. firestore का इस्तेमाल करने के लिए, Firestore डेटाबेस और Cloud Run सेवा खाते पर roles/datastore.user आईएएम भूमिका की भी ज़रूरत होती है. इन-मेमोरी स्टोरेज के साथ सिंगल-इंस्टेंस टेस्टिंग के लिए, --max-instances=1 पास करें.
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID (ज़रूरी नहीं): डिफ़ॉल्ट रूप से, 10 अंकों वाला मैनेजर ग्राहक आईडी (हाइफ़न के बिना) इस्तेमाल किया जाता है. इसका इस्तेमाल तब किया जाता है, जब टूल कॉल में login_customer_id पैरामीटर शामिल नहीं होता.
  • GOOGLE_ADS_MCP_TOOLS_CONFIG (ज़रूरी नहीं): कस्टम tools_config.yaml फ़ाइल का कंटेनर पाथ (उदाहरण के लिए, इमेज को फिर से बनाए बिना, सिर्फ़ पढ़ने वाले मोड को लागू करने के लिए, /etc/mcp/tools_config.yaml पर Secret Manager से माउंट किया गया). टूल के नेमस्पेस और सिर्फ़ पढ़ने वाले मोड को कॉन्फ़िगर करना देखें.

Secret Manager में GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET और GOOGLE_ADS_MCP_JWT_SIGNING_KEY को सेव करें. इसके बाद, सेवा को Google Cloud Run पर डिप्लॉय करें:

gcloud run deploy google-ads-mcp \
  --image=us-central1-docker.pkg.dev/PROJECT_ID/mcp-servers/google-ads-mcp:v0.0.6 \
  --platform=managed \
  --region=us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=CLIENT_ID" \
  --set-secrets="GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=MCP_OAUTH_CLIENT_SECRET:latest,GOOGLE_ADS_MCP_JWT_SIGNING_KEY=MCP_JWT_SIGNING_KEY:latest"

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://CLOUD_RUN_SERVICE_URL"

इनकी जगह ये डालें:

  • PROJECT_ID: आपका Google Cloud प्रोजेक्ट आईडी.
  • CLIENT_ID: आपके OAuth 2.0 वेब ऐप्लिकेशन का क्लाइंट आईडी.
  • MCP_OAUTH_CLIENT_SECRET: Secret Manager में मौजूद सीक्रेट का नाम, जिसमें आपका OAuth 2.0 क्लाइंट सीक्रेट सेव है.
  • MCP_JWT_SIGNING_KEY: Secret Manager में मौजूद सीक्रेट का नाम, जिसमें JWT साइनिंग पासकोड सेव किया गया है.
  • CLOUD_RUN_SERVICE_URL: आपकी Cloud Run सेवा को असाइन किया गया होस्टनेम (उदाहरण के लिए, google-ads-mcp-xyz-uc.a.run.app).

पुष्टि करने और सुरक्षा का मॉडल

--allow-unauthenticated के साथ डिप्लॉय करने पर, Cloud Run के इन्फ़्रास्ट्रक्चर आईएएम की जांच (roles/run.invoker) बंद हो जाती है. इससे बाहरी एआई क्लाइंट, Google Cloud सेवा खाते के टोकन के बिना कनेक्ट हो सकते हैं. इसके बजाय, पुष्टि करने की प्रोसेस को ऐप्लिकेशन लेयर को डेलिगेट किया जाता है:

  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID और GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET सेट होने पर, सर्वर हर अनुरोध पर Google OAuth 2.0 को लागू करता है. साथ ही, पुष्टि नहीं किए गए कॉलर को 401 Unauthorized एचटीटीपी स्टेटस कोड दिखाता है. हर टूल कॉल, कॉल करने वाले की पुष्टि की गई OAuth आइडेंटिटी के तहत एक्ज़ीक्यूट होता है.
  • --allow-unauthenticated को हटाने के लिए, कॉलर को हर अनुरोध के साथ Google Cloud ओआईडीसी आइडेंटिटी टोकन पास करने होंगे. Claude और ChatGPT जैसे स्टैंडर्ड एआई क्लाइंट, Google Cloud IAM टोकन के बजाय असली उपयोगकर्ता के OAuth का इस्तेमाल करते हैं. इसलिए, सीधे कनेक्शन के लिए --allow-unauthenticated को ऐप्लिकेशन-लेवल के OAuth के साथ जोड़ना ज़रूरी है.

एमसीपी क्लाइंट को कॉन्फ़िगर करना

डिप्लॉयमेंट के बाद, Cloud Run सेवा के यूआरएल की मदद से अपने एमसीपी क्लाइंट को कॉन्फ़िगर करें. सर्वर पर OAuth 2.0 लागू होने की वजह से, आपके क्लाइंट को एमसीपी OAuth फ़्लो के साथ काम करना चाहिए या अनुमति वाला धारक टोकन देना चाहिए:

  • OAuth की सुविधा वाले क्लाइंट: एमसीपी OAuth डिस्कवरी की सुविधा वाले क्लाइंट (जैसे, Antigravity) में, कनेक्ट करने पर Google खाते में साइन-इन करने का अनुरोध ट्रिगर होता है. इससे https://www.googleapis.com/auth/adwords स्कोप को अनुमति दी जाती है. यह Google Cloud Console में .../auth/adwords के तौर पर दिखता है.
  • तीसरे पक्ष के एआई प्लैटफ़ॉर्म (Claude, ChatGPT): अपने क्लाइंट की कनेक्टर सेटिंग में, एक कस्टम कनेक्टर जोड़ें. यह कनेक्टर, /mcp पाथ (उदाहरण के लिए, https://google-ads-mcp-xyz-uc.a.run.app/mcp) के साथ आपकी सेवा के यूआरएल पर ले जाना चाहिए. अपने OAuth क्लाइंट आईडी और क्लाइंट सीक्रेट के साथ, OAuth 2.0 से पुष्टि करने का विकल्प चुनें. साथ ही, पुष्टि करें कि क्लाइंट का कॉलबैक यूआरआई, आपके OAuth क्लाइंट के अनुमति वाले रीडायरेक्ट यूआरआई में शामिल हो.
  • OAuth की सुविधा के बिना क्लाइंट: जिन क्लाइंट पर एचटीटीपी OAuth फ़्लो की सुविधा काम नहीं करती उन्हें 401 Unauthorized एचटीटीपी स्टेटस कोड मिलता है. ऐसे क्लाइंट के लिए, लोकल stdio कॉन्फ़िगरेशन का इस्तेमाल करें.

नीचे दिए गए उदाहरण में, ~/.gemini/settings.json में gemini कमांड-लाइन टूल को कॉन्फ़िगर किया गया है. ~/.gemini/config/mcp_config.json में Google Antigravity के लिए, "httpUrl" को "serverUrl" या "url" से बदलें:

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://CLOUD_RUN_SERVICE_URL/mcp"
    }
  }
}

इनकी जगह ये डालें:

  • CLOUD_RUN_SERVICE_URL: आपकी Cloud Run सेवा को असाइन किया गया होस्टनेम (उदाहरण के लिए, google-ads-mcp-xyz-uc.a.run.app).

अगले चरण