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 থেকে আপনার কাছে নিম্নলিখিত ক্রেডেনশিয়াল আছে কিনা তা নিশ্চিত করুন:

কনফিগারেশন

সার্ভারকে 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)।
    • আপনি APIs ও পরিষেবা > OAuth সম্মতি স্ক্রিন > ডেটা অ্যাক্সেস (স্কোপ যোগ করুন বা সরান) বিকল্পের অধীনে OAuth সম্মতি স্ক্রিনে https://www.googleapis.com/auth/adwords স্কোপ যোগ করেছেন।
    • আপনার OAuth সম্মতি স্ক্রিন প্রকাশ করার স্ট্যাটাস টেস্টিং (ডিফল্ট) হিসেবে সেট করা থাকলে, আপনি APIs ও পরিষেবা > OAuth সম্মতি স্ক্রিন > দর্শক (টেস্ট ব্যবহারকারী > + ব্যবহারকারী যোগ করুন) বিকল্পের অধীনে MCP সার্ভারের সাথে কানেক্ট করা Google অ্যাকাউন্ট টেস্ট ব্যবহারকারী হিসেবে যোগ করেছেন।
  • 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 প্রয়োজন।

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 পাথ সহ আপনার Cloud Run URL-এ পয়েন্ট করে এমন একটি কাস্টম কানেক্টর যোগ করুন (যেমন, https://your-cloud-run-url.a.run.app/mcp), 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"।

    ডেটার স্ট্রাকচার এবং কোয়েরি করার জন্য কোন কোন ফিল্ড উপলভ্য তা বুঝতে এটি সহায়ক।

শুরু করার জন্য স্যাম্পেল প্রম্পট

সার্ভার কী করতে পারে তা জিজ্ঞাসা করুন:

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

পরবর্তী ধাপ