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

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

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

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

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

• कम्यूनिटी: Google Advertising Community Discord पर #ads-api-ai-tools चैनल से जुड़ें.

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

इस एमसीपी सर्वर को लागू करने से, आपको Google Ads API की पुष्टि करने, संसाधन फ़ेच करने, और डेटा पार्स करने के लिए कस्टम "ग्लू कोड" लिखने की ज़रूरत नहीं पड़ती. सर्वर, कुछ खास टूल दिखाता है. एलएलएम, इन टूल को अपने-आप ढूंढ सकता है और इस्तेमाल कर सकता है.

मुख्य स्पेसिफ़िकेशन

• प्रोटोकॉल: एमसीपी (मॉडल कॉन्टेक्स्ट प्रोटोकॉल)
• मोड: रीड-ओनली (मौजूदा रिलीज़)
• भाषा: Python
• ट्रांसपोर्ट: स्टैंडर्ड इनपुट/आउटपुट (stdio) या स्ट्रीम किया जा सकने वाला एचटीटीपी (streamable-http / Cloud Run)
• पुष्टि करना: OAuth 2.0 या सेवा खाता

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

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

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

Google Ads एमसीपी सर्वर को कॉन्फ़िगर और इस्तेमाल करने के लिए, यह तरीका अपनाएं.

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

कॉन्फ़िगरेशन से पहले, पक्का करें कि आपके पास Google Cloud console से मिले ये क्रेडेंशियल हों:

• प्रोजेक्ट आईडी: आपके Google Cloud प्रोजेक्ट का आईडी (GOOGLE_PROJECT_ID). Google Ads API की खास जानकारी देने वाले पेज पर जाकर पक्का करें कि आपके प्रोजेक्ट के पास एक्सप्लोरर ऐक्सेस, बुनियादी ऐक्सेस या स्टैंडर्ड ऐक्सेस लेवल हो. अगर आपके पास इनमें से कोई ऐक्सेस लेवल नहीं है, तो इनमें से किसी एक ऐक्सेस लेवल के लिए आवेदन करें. ध्यान दें कि डेवलपर टोकन (GOOGLE_ADS_DEVELOPER_TOKEN) 9 सितंबर, 2026 को बंद कर दिए गए थे. अब Google Ads MCP सर्वर के नए वर्शन में इनकी ज़रूरत नहीं है, क्योंकि एपीआई ऐक्सेस लेवल, Google Cloud प्रोजेक्ट से जुड़े होते हैं.
• OAuth क्रेडेंशियल: OAuth 2.0 क्लाइंट आईडी/क्लाइंट सीक्रेट पेयर या ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल का सेट.

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

सर्वर को एमसीपी के साथ काम करने वाले होस्ट में इंटिग्रेट करने के लिए, अपने होस्ट की एमसीपी कॉन्फ़िगरेशन फ़ाइल में यह एंट्री जोड़ें. जैसे, settings.json. साथ ही, GOOGLE_APPLICATION_CREDENTIALS को अपनी एडीसी JSON फ़ाइल पर ले जाएं या 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 Ads का एमसीपी सर्वर, आपके एआई क्लाइंट को लाइव खाते के डेटा का रीड-ओनली ऐक्सेस देता है. अपने एजेंट को मान्य Google Ads क्वेरी लैंग्वेज (GAQL) क्वेरी बनाने, खाते की परफ़ॉर्मेंस में होने वाले बदलावों का विश्लेषण करने, और क्लाइंट लाइब्रेरी कोड जनरेट करने में मदद करने के लिए, एमसीपी सर्वर को इन टूल के साथ जोड़ें:

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

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

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

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

1. एक Google Cloud प्रोजेक्ट.

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

   gcloud config set project YOUR_PROJECT_ID
   

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

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 की मदद से पुष्टि करने के लिए, OAuth 2.0 क्लाइंट आईडी (आपके Google Cloud प्रोजेक्ट में वेब ऐप्लिकेशन के तौर पर कॉन्फ़िगर किया गया है). पक्का करें कि:
  • आपने उन सभी एआई क्लाइंट के लिए अनुमति वाले सही रीडायरेक्ट यूआरआई जोड़े हैं जिन्हें आपको कनेक्ट करना है. जैसे, https://claude.ai/api/mcp/auth_callback, https://chatgpt.com/connector_platform_oauth_redirect या https://antigravity.google/oauth-callback.
  • आपने एपीआई और सेवाएं > ऐसी स्क्रीन जहां 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. Google Cloud Run, शुरुआती डिप्लॉयमेंट के दौरान यह यूआरएल जनरेट करता है. इसलिए, पहले इस वैरिएबल के बिना डिप्लॉय करें. इसके बाद, डिप्लॉयमेंट के बाद सेवा को अपडेट करें.
• FASTMCP_HOST: इसे 0.0.0.0 पर सेट करें, ताकि FastMCP सभी आईपी पतों से कनेक्शन स्वीकार कर सके.

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

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

चेतावनी: --allow-unauthenticated के साथ डिप्लॉय करते समय, GOOGLE_ADS_MCP_OAUTH_CLIENT_ID और GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET को कभी भी न हटाएं. ये एनवायरमेंट वैरिएबल, सर्वर को लोकल stdio मोड से streamable-http ट्रांसपोर्ट पर स्विच करने के लिए ट्रिगर करते हैं. इनके बिना, सर्वर पुष्टि करने की प्रक्रिया को लागू नहीं कर सकता. साथ ही, वह ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल (एडीसी) पर वापस चला जाता है. इससे कंटेनर के सेवा खाते के क्रेडेंशियल, उन कॉलर को दिखते हैं जिनकी पुष्टि नहीं हुई है.

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

डिप्लॉयमेंट के बाद, 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://your-cloud-run-url.a.run.app/mcp) वाले आपके Cloud Run यूआरएल पर ले जाना चाहिए. इसके बाद, OAuth 2.0 से पुष्टि करने का तरीका चुनें. इसके लिए, अपने OAuth क्लाइंट आईडी और क्लाइंट सीक्रेट का इस्तेमाल करें. साथ ही, पक्का करें कि क्लाइंट का कॉलबैक यूआरआई, आपके OAuth क्लाइंट के अनुमति वाले रीडायरेक्ट यूआरआई में जोड़ा गया हो. (होस्ट किए गए एंडपॉइंट के पायलट प्रोग्राम में शामिल होने की अनुमति वाली सूची में शामिल लोग, होस्ट किए गए एमसीपी सेटअप की गाइड भी देख सकते हैं.)
• OAuth की सुविधा के बिना काम करने वाले क्लाइंट: एचटीटीपी OAuth फ़्लो के साथ काम न करने वाले क्लाइंट को एचटीटीपी 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 डेवलपर असिस्टेंट का इस्तेमाल करें. एमसीपी सेटअप और खाते की गड़बड़ी का पता लगाने वाले वर्कफ़्लो के बारे में सिलसिलेवार निर्देश पाने के लिए, 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 Developer Assistant के बारे में जानकारी
• Google Ads API Developer Assistant को इंस्टॉल और इस्तेमाल करना