سرور MCP را برای Google Analytics امتحان کنید. از GitHub نصب کنید و برای جزئیات بیشتر به اطلاعیه مراجعه کنید.

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

امتحان کردن سرور Google Analytics MCP

سرور Google Analytics Model Context Protocol (MCP) به شما امکان می‌دهد داده‌های Google Analytics خود را به مدل‌های زبانی بزرگ (LLM) و عامل‌های هوش مصنوعی، مانند Gemini، متصل کنید. می‌توانید از سرور MCP برای پُرسمان کردن گزارش‌ها به زبان طبیعی، بررسی پیکربندی‌های دارایی، و ساختن عامل‌های تجزیه‌وتحلیل سفارشی استفاده کنید.

راه‌اندازی سرور MCP مشاهده در GitHub تماشای آموزش راه‌اندازی

پیش‌نیازها

قبل‌از پیکربندی سرور MCP در Google Analytics، الزامات زیر را تکمیل کنید:

Python و یک اجراکننده بسته را نصب کنید:
- Python 3.10 یا بالاتر را نصب کنید.
- pipx یا uv (uvx) را نصب کنید تا سرور MCP را در محیط Python مجزا اجرا کنید.
Google Analytics API را در فعال کنید:
- پروژه‌ای را ایجاد یا انتخاب کنید.
- Google Analytics Admin API (analyticsadmin.googleapis.com) و Google Analytics Data API (analyticsdata.googleapis.com) را در پروژه‌تان فعال کنید:
```
gcloud services enable analyticsadmin.googleapis.com \
  analyticsdata.googleapis.com \
  --project=YOUR_PROJECT_ID
```
اعطای دسترسی به دارایی Google Analytics:
- در رابط کاربری Google Analytics، حداقل نقش بیننده (roles/analytics.viewer) را در دارایی Google Analytics هدف به حساب کاربری یا حساب سرویس خود اعطا کنید. برای دریافت دستورالعمل‌ها، به مدیریت دسترسی و مدیریت محدودیت داده مراجعه کنید.

راه‌اندازی اصالت‌سنجی

سرور Google Analytics MCP بااستفاده از اعتبارنامه‌های پیش‌فرض برنامه (ADC) با گستره Google Analytics OAuth 2.0 فقط‌خواندنی اصالت‌سنجی می‌کند:

https://www.googleapis.com/auth/analytics.readonly

می‌توانید ADC را بااستفاده از حساب کاربری Google یا حساب سرویس پیکربندی کنید.

گزینه ۱: اصالت‌سنجی با اطلاعات اعتباری کاربر

gcloud CLI را نصب و مقداردهی اولیه کنید.

gcloud auth application-default login را با دامنه‌های لازم اجرا کنید:

gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform"

اگر از فایل پیکربندی کارخواه وب یا رایانه OAuth 2.0 بارگیری‌شده استفاده می‌کنید (به مدیریت کارخواه‌های OAuth مراجعه کنید)، --client-id-file را ارسال کنید:

gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform" \
  --client-id-file=YOUR_CLIENT_JSON_FILE

وقتی فرمان تمام شد، مسیر اعتبارنامه‌های چاپ‌شده در کنسول (Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]) را کپی کنید. هنگام پیکربندی کارخواه MCP، از این مسیر در GOOGLE_APPLICATION_CREDENTIALS استفاده می‌کنید.

گزینه ۲: اصالت‌سنجی با حساب سرویس

برای اصالت‌سنجی با حساب سرویس که دسترسی بیننده به دارایی Google Analytics شما دارد:

فایل کلید JSON حساب خدماتی: GOOGLE_APPLICATION_CREDENTIALS را در پیکربندی کارخواه MCP خود روی مسیر مطلق فایل JSON حساب خدماتی‌تان تنظیم کنید.

جعل هویت حساب سرویس: با جعل هویت حساب سرویس با gcloud CLI، اطلاعات اعتباری ADC تولید کنید:

gcloud auth application-default login \
  --impersonate-service-account=SERVICE_ACCOUNT_EMAIL \
  --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform"

پیکربندی کردن کارخواه MCP

این سرور در PyPI به‌عنوان analytics-mcp منتشر شده است و هر دو اسکریپت کنسول analytics-mcp و google-analytics-mcp را نمایش می‌دهد.

در پیکربندی‌های زیر، این موارد را جایگزین کنید:

PATH_TO_CREDENTIALS_JSON را با مسیر مطلق به ADC یا فایل JSON حساب سرویس خود جایگزین کنید.
YOUR_PROJECT_ID را با شناسه پروژه که در آن میاناهای برنامه‌سازی کاربردی Google Analytics را فعال کرده‌اید جایگزین کنید.

‫Antigravity CLI و Antigravity IDE

Antigravity CLI یا Antigravity IDE را نصب کنید.

سرور analytics-mcp را به ~/.gemini/config/mcp_config.json (یا .agents/mcp_config.json در فضای کاری‌تان) اضافه کنید:

{
  "mcpServers": {
    "analytics-mcp": {
      "command": "pipx",
      "args": ["run", "analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

مطمئن شوید analytics-mcp متصل باشد:
- Antigravity CLI: agy را اجرا کنید، سپس /mcp را وارد کنید تا سرورهای MCP پیکربندی‌شده‌تان را ببینید.
- Antigravity IDE: تنظیمات > سفارشی‌سازی‌ها > سرورهای MCP نصب‌شده را باز کنید و روی بازآوری کلیک کنید.

‫Claude Desktop و Claude Code

برای Claude Desktop، سرور را به فایل claude_desktop_config.json خود اضافه کنید (~/Library/Application Support/Claude/claude_desktop_config.json در macOS یا %APPDATA%\Claude\claude_desktop_config.json در Windows):

{
  "mcpServers": {
    "analytics-mcp": {
      "command": "pipx",
      "args": ["run", "analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

برای Claude Code، سرور را بااستفاده از ابزار خط فرمان ثبت کنید:

claude mcp add analytics-mcp \
  --scope user \
  -e GOOGLE_APPLICATION_CREDENTIALS="PATH_TO_CREDENTIALS_JSON" \
  -e GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" \
  -- pipx run analytics-mcp

مکان‌نما

سرور را به .cursor/mcp.json در فهرست راهنمای پروژه (یا ~/.cursor/mcp.json برای پیکربندی سراسری) اضافه کنید. می‌توانید google-analytics-mcp را بااستفاده از uvx یا pipx فراخوانی کنید:

{
  "mcpServers": {
    "google-analytics-mcp": {
      "command": "uvx",
      "args": ["--from", "analytics-mcp", "google-analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

برای اجرای جدیدترین نسخه توسعه مستقیماً از GitHub بااستفاده از uvx، "args" را به‌روز کنید:

"args": [
  "--from",
  "git+https://github.com/googleanalytics/google-analytics-mcp.git",
  "google-analytics-mcp"
]

یا برای استفاده از pipx، "command" را به "pipx" تغییر دهید و "args" را روی این مقدار تنظیم کنید:

"command": "pipx",
"args": [
  "run",
  "--spec",
  "git+https://github.com/googleanalytics/google-analytics-mcp.git",
  "google-analytics-mcp"
]

ابزارهای MCP دردسترس

سرور MCP در Google Analytics از Admin API و Data API v1 برای نمایش ابزارهای فقط خواندنی به کارخواه MCP شما استفاده می‌کند:

کاوش حساب و دارایی (Admin API):
- get_account_summaries: حساب‌ها و دارایی‌های Google Analytics را که برای کاربر اصالت‌سنجی‌شده (accountSummaries.list) قابل‌دسترسی است فهرست می‌کند.
- get_property_details: جزئیات پیکربندی را برای دارایی Google Analytics خاصی برمی‌گرداند (properties.get).
- list_google_ads_links: پیوندهای حساب‌های Google Ads را برای یک دارایی (properties.googleAdsLinks.list) فهرست می‌کند.
- list_property_annotations: حاشیه‌نویسی‌های پیکربندی‌شده برای یک دارایی را فهرست می‌کند (properties.reportingDataAnnotations.list).
گزارش‌دهی و بازرسی طرح‌واره (Data API v1):
- get_custom_dimensions_and_metrics: ابعاد سفارشی و سنجه‌های سفارشی تعریف‌شده برای دارایی (getMetadata) را بازیابی می‌کند.
- run_report: گزارش استاندارد Google Analytics را اجرا می‌کند (runReport).
- run_realtime_report: گزارش هم‌زمان Google Analytics را اجرا می‌کند (runRealtimeReport).
- run_funnel_report: گزارش کاوش قیفی Google Analytics را اجرا می‌کند (runFunnelReport).
- run_conversions_report: گزارش عملکرد تبدیل‌ها (runConversionsReport) را اجرا می‌کند.

پیام‌واره‌های نمونه

پس‌از اتصال، سؤالاتی مانند موارد زیر را از دستیار هوش مصنوعی بپرسید:

دیروز چند کاربر داشتم؟
دیروز محصولات پرفروش من کدام‌ها بودند؟
بودجه بازاریابی من ۵۰۰۰ دلار در ماه است و باید درآمد بیشتری کسب کنم. کمک کن تا یک طرح بازاریابی داده‌محور بسازم.
چه ابعاد سفارشی و سنجه‌های سفارشی‌ای در دارایی من پیکربندی شده است؟
محبوب‌ترین رویدادها در دارایی Google Analytics من در ۹۰ روز گذشته کدامند؟

عیب‌یابی

برای حل‌وفصل کردن خطاهای رایج راه‌اندازی و زمان اجرا، از بازبینه زیر استفاده کنید:

403 PERMISSION_DENIED (میانای برنامه‌سازی کاربردی فعال نیست یا اجازه‌های دارایی کافی نیست):
- مطمئن شوید که هم Google Analytics Admin API (analyticsadmin.googleapis.com) و هم Google Analytics Data API (analyticsdata.googleapis.com) در پروژه مشخص‌شده توسط GOOGLE_CLOUD_PROJECT فعال باشند.
- تأیید کنید که کاربر یا حساب سرویس اصالت‌سنجی‌کننده حداقل نقش بیننده (roles/analytics.viewer) را در دارایی Google Analytics هدف در رابط کاربری Google Analytics داشته باشد.
- اگر خطا Request had insufficient authentication scopes را نشان می‌دهد، gcloud auth application-default login را با https://www.googleapis.com/auth/analytics.readonly و https://www.googleapis.com/auth/cloud-platform دوباره اجرا کنید.
پروژه سهمیه (GOOGLE_CLOUD_PROJECT) یا 403 ACCESS_NOT_CONFIGURED وجود ندارد:
- درخواست‌های اصالت‌سنجی‌شده با اطلاعات اعتباری ADC کاربر به پروژه سهمیه با میاناهای برنامه‌سازی کاربردی Google Analytics فعال‌شده نیاز دارند. "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID" را در پیکربندی env سرور MCP خود تنظیم کنید، یا پروژه سهمیه را در فایل ADC خود تنظیم کنید:
```
gcloud auth application-default set-quota-project YOUR_PROJECT_ID
```
401 UNAUTHENTICATED یا فایل اطلاعات کاربری پیدا نشد:
- از مسیر مطلق برای GOOGLE_APPLICATION_CREDENTIALS استفاده کنید (برای مثال، /Users/username/.config/gcloud/application_default_credentials.json). از متغیرهای ~ یا $HOME استفاده نکنید، زیرا بسیاری از میزبان‌های MCP متغیرهای پوسته را در فایل‌های پیکربندی JSON گسترش نمی‌دهند.
- اگر اعتبارنامه کاربری‌تان منقضی شده است، gcloud auth application-default login را دوباره اجرا کنید.
سرور راه‌اندازی نمی‌شود (spawn pipx ENOENT، uvx: command not found، یا خطاهای نسخه Python):
- مطمئن شوید Python نسخه ۳.۱۰ یا بالاتر نصب شده باشد (python3 --version).
- برنامه‌های GUI رایانه (مانند Claude Desktop و Cursor) اغلب پوسته تعاملی PATH شما را به ارث نمی‌برند. "pipx" یا "uvx" را در "command" با مسیر دودویی مطلق برگردانده‌شده توسط which pipx یا which uvx (برای مثال، /opt/homebrew/bin/pipx یا /Users/username/.local/bin/pipx) جایگزین کنید.