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

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

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

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

এই 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. এক্সিকিউশন: MCP সার্ভার Google Ads API-কে কোয়েরি করার জন্য অন্তর্নিহিত Python লজিক এক্সিকিউট করে।
  4. কনটেক্সট ইনজেকশন: LLM-এর কনটেক্সট উইন্ডোতে স্ট্রাকচার্ড ফলাফল ফেরত পাঠানো হয়।
  5. উত্তর: LLM ডেটা সিন্থেসাইজ করে মানুষের-পঠনযোগ্য উত্তর তৈরি করে।

শুরু করুন

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

পূর্বশর্ত

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

কনফিগারেশন

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 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 প্রয়োজন।

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: রিসোর্স মেট্রিক, বাজেট ও স্ট্যাটাস পেতে 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