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

मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) एक ओपन स्टैंडर्ड है. इसकी मदद से, बड़े लैंग्वेज मॉडल (एलएलएम), बाहरी डेटा और ऐप्लिकेशन के साथ सुरक्षित तरीके से इंटरैक्ट कर सकते हैं. Google Ads MCP सर्वर, 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 से मिले ये क्रेडेंशियल हों:

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

सर्वर को एमसीपी के साथ काम करने वाले होस्ट में इंटिग्रेट करने के लिए, अपने होस्ट की एमसीपी कॉन्फ़िगरेशन फ़ाइल में यह एंट्री जोड़ें. जैसे, 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 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 सहमति स्क्रीन के पब्लिशिंग स्टेटस को Testing (डिफ़ॉल्ट) पर सेट किया गया है, तो आपने MCP सर्वर से कनेक्ट होने वाले Google खातों को APIs & Services > 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 इन्फ़्रास्ट्रक्चर IAM लागू होता है. इसके लिए, कॉल करने वालों को हर अनुरोध के साथ Google Cloud OIDC आइडेंटिटी टोकन पास करने होते हैं. Claude और ChatGPT जैसे स्टैंडर्ड एआई क्लाइंट, Google Cloud IAM आइडेंटिटी टोकन के बजाय असली उपयोगकर्ता के OAuth का इस्तेमाल करके पुष्टि करते हैं. इसलिए, इन प्लैटफ़ॉर्म से सीधे कनेक्ट करने के लिए, ऐप्लिकेशन-लेवल के OAuth के साथ --allow-unauthenticated की ज़रूरत होती है.

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

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

  • OAuth की सुविधा वाले क्लाइंट: ऐसे क्लाइंट जो एमसीपी OAuth डिस्कवरी के साथ काम करते हैं (जैसे, Antigravity), एंडपॉइंट से कनेक्ट करने पर, Google से साइन इन करने और https://www.googleapis.com/auth/adwords स्कोप (Google Cloud Console में .../auth/adwords के तौर पर लिस्ट किया गया है) को अनुमति देने के लिए, पुष्टि करने का प्रॉम्प्ट ट्रिगर करते हैं.
  • तीसरे पक्ष के एआई प्लैटफ़ॉर्म (Claude, ChatGPT): अपने क्लाइंट के कनेक्टर या इंटिग्रेशन सेटिंग में, एक कस्टम कनेक्टर जोड़ें. यह कनेक्टर, /mcp पाथ के साथ आपके Cloud Run यूआरएल पर रीडायरेक्ट करता हो. उदाहरण के लिए, https://your-cloud-run-url.a.run.app/mcp. इसके बाद, 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: यह संसाधन की मेट्रिक, बजट, और स्टेटस को फ़ेच करने के लिए, 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