Google Ads MCP সার্ভার: ডেভেলপার ইন্টিগ্রেশন নির্দেশিকা

মডেল কন্টেক্সট প্রোটোকল (MCP) হল একটি ওপেন স্ট্যান্ডার্ড যা লার্জ ল্যাঙ্গুয়েজ মডেলকে (LLM) এক্সটার্নাল ডেটা ও অ্যাপ্লিকেশনের সাথে নিরাপদে ইন্টার‍্যাক্ট করার সুবিধা দেয়। Google Ads MCP সার্ভার Google Ads API-এর সাথে একটি স্ট্যান্ডার্ডাইজড ব্রিজ প্রদান করে, যা AI এজেন্টদের ন্যাচারাল ল্যাঙ্গুয়েজ ব্যবহার করে ক্যাম্পেন ডেটা বিশ্লেষণ এবং রিট্রিভ করতে দেয়।

কমিউনিটি রিসোর্স ও সহায়তা

• GitHub রিপোজিটরি: google-ads-mcp রিপোজিটরিতে ডেমো, উদাহরণ খুঁজুন এবং সমস্যার রিপোর্ট করুন বা ফিচারের সাজেশন দিন।

  সমস্যার রিপোর্ট ও নতুন ফিচারের অনুরোধের জন্য সমস্যা ট্যাব ব্যবহার করুন।

• কমিউনিটি: Google Advertising Community Discord-এ #ads-api-ai-tools চ্যানেলে যোগ দিন।

প্রযুক্তিগত ওভারভিউ

এই MCP সার্ভার প্রয়োগ করার মাধ্যমে, Google Ads API যাচাইকরণ, রিসোর্স ফেচিং এবং ডেটা পার্সিংয়ের জন্য কাস্টম "গ্লু কোড" লেখার প্রয়োজনীয়তা আপনি দূর করেন। সার্ভারটি নির্দিষ্ট টুল প্রকাশ করে যা একটি LLM স্বাধীনভাবে আবিষ্কার এবং আহ্বান করতে পারে।

গুরুত্বপূর্ণ স্পেসিফিকেশন

• প্রোটোকল: MCP (Model Context Protocol)
• মোড: শুধুমাত্র-পঠনযোগ্য (বর্তমান রিলিজ)
• ভাষা: Python
• ট্রান্সপোর্ট: স্ট্যান্ডার্ড ইনপুট/আউটপুট (stdio) বা স্ট্রিমেবল HTTP (streamable-http / Cloud Run)
• যাচাইকরণ: OAuth 2.0 বা পরিষেবা অ্যাকাউন্ট

ইন্টার‍্যাকশন লুপ কীভাবে কাজ করে

1. অনুরোধ: ব্যবহারকারী কোনও কোয়েরি জমা দেন, যেমন "এই সপ্তাহে আমার ক্যাম্পেনের পারফর্ম্যান্স কেমন?".
2. খোঁজা: LLM তার উপলভ্য টুলগুলি পরীক্ষা করে এবং google-ads-mcp সার্চ করার ক্ষমতা শনাক্ত করে।
3. এক্সিকিউশন: Google Ads API কোয়েরি করার জন্য MCP সার্ভার অন্তর্নিহিত Python লজিক এক্সিকিউট করে।
4. কনটেক্সট ইনজেকশন: LLM-এর কনটেক্সট উইন্ডোতে স্ট্রাকচার্ড ফলাফল ফেরত পাঠানো হয়।
5. উত্তর: LLM ডেটা সিন্থেসাইজ করে মানুষের-পঠনযোগ্য উত্তর তৈরি করে।

শুরু করুন

Google Ads MCP সার্ভার কনফিগার ও ব্যবহার করতে, এইসব ধাপ অনুসরণ করুন।

পূর্বশর্ত

কনফিগার করার আগে, আপনার কাছে Google Cloud Console থেকে নিম্নলিখিত ক্রেডেনশিয়াল আছে কিনা তা নিশ্চিত করুন:

• প্রোজেক্ট আইডি: আপনার 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 ফাইলে পয়েন্ট করুন (অথবা gcloud auth application-default login-এর মাধ্যমে ডিফল্ট ADC কনফিগার করুন)। আপনি ম্যানেজার অ্যাকাউন্টের মাধ্যমে অ্যাকাউন্ট অ্যাক্সেস করলে, 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 MCP সার্ভার আপনার AI ক্লায়েন্টকে লাইভ অ্যাকাউন্ট ডেটার শুধু পড়ার অ্যাক্সেস দেয়। আপনার এজেন্টকে সঠিক 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 Developer Assistant: Google Antigravity এবং Claude Code-এর জন্য একটি মডিউলার প্লাগ-ইন যা লোকাল Protobuf স্কিমা ইন্সপেকশন, প্রোগ্রাম্যাটিক GAQL যাচাইকরণ, ক্লায়েন্ট লাইব্রেরি কোড জেনারেশন (মিউটেট স্ক্রিপ্ট সহ) এবং অফলাইন কনভার্সন সংক্রান্ত সমস্যার সমাধান করার সুবিধা প্রদান করে। Google Ads API Developer Assistant কী? থেকে এটি কীভাবে কাজ করে তা জানুন অথবা ইনস্টল করার নির্দেশিকা অনুসরণ করুন।

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 যাচাইকরণের জন্য OAuth 2.0 ক্লায়েন্ট আইডি (আপনার Google Cloud প্রোজেক্টে ওয়েব অ্যাপ্লিকেশন হিসেবে কনফিগার করা)। নিশ্চিত করুন যে:
  • আপনি কানেক্ট করার পরিকল্পনা করছেন এমন যেকোনও AI ক্লায়েন্টের জন্য উপযুক্ত অনুমোদিত রিডাইরেক্ট 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 কনসেন্ট স্ক্রিনে API ও পরিষেবা > OAuth কনসেন্ট স্ক্রিন > ডেটা অ্যাক্সেস (স্কোপ যোগ করুন বা সরান) বিকল্পের অধীনে যোগ করেছেন।
  • আপনার OAuth সম্মতি স্ক্রিন প্রকাশ করার স্ট্যাটাস Testing (ডিফল্ট) হিসেবে সেট করা থাকলে, আপনি MCP সার্ভারের সাথে কানেক্ট করা Google অ্যাকাউন্টগুলি APIs & Services > OAuth consent screen > Audience (Test users > + Add users)-এর অধীনে Test users হিসেবে যোগ করেছেন।
• GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: OAuth ক্লায়েন্ট আইডির সাথে সংশ্লিষ্ট OAuth ক্লায়েন্ট সিক্রেট।
• GOOGLE_ADS_MCP_BASE_URL: আপনার MCP সার্ভার যেখানে অ্যাক্সেসযোগ্য সেখানে পাবলিক বেস URL (যেমন, https://google-ads-mcp-xyz-uc.a.run.app)। কারণ Google Cloud Run প্রাথমিক ডিপ্লয়মেন্টের সময় এই URL তৈরি করে, প্রথমে এই ভেরিয়েবল ছাড়াই ডিপ্লয় করুন, তারপর ডিপ্লয়মেন্টের পরে পরিষেবা আপডেট করুন।
• FASTMCP_HOST: FastMCP-কে সব IP অ্যাড্রেস থেকে কানেকশন গ্রহণ করার অনুমতি দিতে এটি 0.0.0.0-এ সেট করুন।

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 ডিপ্লয়মেন্ট সম্পূর্ণ করার পরে, অ্যাসাইন করা পরিষেবা URL ফিরিয়ে আনুন এবং 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-এর ইনফ্রাস্ট্রাকচার-লেভেল IAM চেক (roles/run.invoker) বন্ধ হয়ে যায় যাতে এক্সটার্নাল AI ক্লায়েন্টরা 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 আইডেন্টিটি টোকেন পাস করতে হয়। কারণ স্ট্যান্ডার্ড AI ক্লায়েন্ট (যেমন 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 ট্রান্সপোর্টে পরিবর্তন করতে ট্রিগার করে। এগুলি ছাড়া, সার্ভার যাচাইকরণ এনফোর্স করতে পারে না এবং অ্যাপ্লিকেশন ডিফল্ট ক্রেডেনশিয়াল (ADC) ব্যবহার করে, যার ফলে যাচাই না করা কলারদের কাছে কন্টেনারের পরিষেবা অ্যাকাউন্ট ক্রেডেনশিয়াল প্রকাশ হয়ে যায়।

MCP ক্লায়েন্ট কনফিগার করুন

ডিপ্লয় করার পরে, Cloud Run URL-এর মাধ্যমে আপনার MCP ক্লায়েন্ট কনফিগার করুন। সার্ভারের জন্য OAuth 2.0 যাচাইকরণ প্রয়োজন, তাই ক্লায়েন্টকে অবশ্যই MCP OAuth ফ্লো সমর্থন করতে হবে বা একটি অনুমোদিত বিয়ারার টোকেন প্রদান করতে হবে:

• OAuth-চালু থাকা ক্লায়েন্ট: যেসব ক্লায়েন্ট MCP OAuth ডিসকভারি সাপোর্ট করে (যেমন Antigravity), এন্ডপয়েন্টে কানেক্ট করলে Google-এর মাধ্যমে সাইন-ইন করার জন্য যাচাইকরণ প্রম্পট ট্রিগার হয় এবং https://www.googleapis.com/auth/adwords স্কোপের অনুমতি দেয় (Google Cloud কনসোলে .../auth/adwords হিসেবে তালিকাভুক্ত)।
• থার্ড-পার্টি AI প্ল্যাটফর্ম (Claude, ChatGPT): আপনার ক্লায়েন্টের কানেক্টর বা ইন্টিগ্রেশন সেটিংসে, /mcp পাথ (যেমন, https://your-cloud-run-url.a.run.app/mcp) সহ আপনার Cloud Run URL-এ পয়েন্ট করে এমন একটি কাস্টম কানেক্টর যোগ করুন, OAuth 2.0 যাচাইকরণ বেছে নিন (আপনার নিজস্ব OAuth ক্লায়েন্ট আইডি এবং ক্লায়েন্ট সিক্রেট ব্যবহার করে) এবং ক্লায়েন্টের কলব্যাক URI আপনার OAuth ক্লায়েন্টের অনুমোদিত রিডাইরেক্ট URI-তে যোগ করা হয়েছে কিনা তা নিশ্চিত করুন। (হোস্ট করা এন্ডপয়েন্ট পাইলটের অনুমোদিত অংশগ্রহণকারীরাও হোস্ট করা MCP সেট-আপ গাইড দেখতে পারেন।)
• OAuth কাজ করে না এমন ক্লায়েন্ট: HTTP OAuth ফ্লো কাজ করে না এমন ক্লায়েন্ট HTTP 401 অননুমোদিত রেসপন্স পাবে। এইসব টুলের জন্য, পরিবর্তে লোকাল 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 Developer Assistant ব্যবহার করুন। গাইডেড 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 Developer Assistant সম্পর্কে জানুন
• Google Ads API Developer Assistant ইনস্টল ও ব্যবহার করা