جرِّب خادم MCP لخدمة "إحصاءات Google". يمكنك تثبيت التطبيق من GitHub والاطّلاع على الإعلان لمعرفة المزيد من التفاصيل.

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

تجربة خادم MCP في "إحصاءات Google"

يتيح لك خادم بروتوكول سياق النموذج (MCP) في "إحصاءات Google" ربط بياناتك في "إحصاءات Google" بالنماذج اللغوية الكبيرة (LLM) ووكلاء الذكاء الاصطناعي، مثل Gemini. يمكنك استخدام خادم MCP للاستعلام عن التقارير بلغة طبيعية، وفحص إعدادات المواقع، وإنشاء وكلاء إحصاءات مخصّصين.

إعداد خادم MCP العرض على GitHub مشاهدة الفيديو التعليمي حول الإعداد

المتطلبات الأساسية

قبل ضبط خادم MCP في "إحصاءات Google"، يجب إكمال المتطلبات التالية:

ثبِّت Python وأداة تشغيل الحِزم:
- ثبِّت الإصدار 3.10 من Python أو إصدارًا أحدث.
- ثبِّت pipx أو uv (uvx) لتشغيل خادم MCP في بيئة Python معزولة.
فعِّل Google Analytics APIs في :
- أنشِئ مشروعًا أو اختَره.
- فعِّل كلاً من 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":
- في واجهة مستخدم "إحصاءات Google"، امنح حساب المستخدم أو حساب الخدمة دور المُشاهد (roles/analytics.viewer) على الأقل في الموقع المستهدَف على "إحصاءات Google". للحصول على التعليمات، يُرجى الاطّلاع على مقالة إدارة أذونات الوصول والقيود المفروضة على البيانات.

إعداد المصادقة

يُجري خادم MCP في "إحصاءات Google" المصادقة باستخدام بيانات الاعتماد التلقائية للتطبيق (ADC) مع نطاق OAuth 2.0 بإذن القراءة فقط في "إحصاءات Google":

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

يمكنك ضبط ADC باستخدام حساب مستخدم Google أو حساب خدمة.

الخيار 1: المصادقة باستخدام بيانات اعتماد المستخدم

ثبِّت 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]). يمكنك استخدام هذا المسار في GOOGLE_APPLICATION_CREDENTIALS عند ضبط عميل MCP.

الخيار 2: المصادقة باستخدام حساب خدمة

للمصادقة باستخدام حساب خدمة لديه إذن وصول المُشاهد إلى موقعك على "إحصاءات Google"، اتّبِع الخطوات التالية:

ملف مفتاح JSON لحساب الخدمة: اضبط GOOGLE_APPLICATION_CREDENTIALS في إعدادات عميل MCP على المسار المطلق لملف JSON الخاص بحساب الخدمة.

انتحال هوية حساب الخدمة: يمكنك إنشاء بيانات اعتماد ADC من خلال انتحال هوية حساب الخدمة باستخدام gcloud CLI:

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 بالمسار المطلق إلى ملف JSON الخاص ببيانات الاعتماد التلقائية للتطبيق (ADC) أو حساب الخدمة.
YOUR_PROJECT_ID باستخدام رقم تعريف المشروع الذي فعّلت فيه واجهات Google Analytics API.

‫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" كلاً من Admin API والإصدار 1 من Data API لعرض أدوات بإذن بالقراءة فقط لعميل MCP:

استكشاف الحسابات والمواقع (Admin API):
- get_account_summaries: تعرض هذه الطريقة حسابات ومواقع "إحصاءات Google" التي يمكن للمستخدم الذي تمّت مصادقته الوصول إليها (accountSummaries.list).
- ‫get_property_details: تعرض هذه الطريقة تفاصيل الإعدادات لموقع معيّن على "إحصاءات Google" (properties.get).
- ‫list_google_ads_links: تعرض هذه الطريقة روابط إلى حسابات "إعلانات Google" لموقع معيّن (properties.googleAdsLinks.list).
- ‫list_property_annotations: تعرض هذه الطريقة قائمة بالتعليقات التوضيحية التي تم ضبطها لموقع إلكتروني (properties.reportingDataAnnotations.list).
إعداد التقارير وفحص المخطط (الإصدار 1 من Data API):
- get_custom_dimensions_and_metrics: لاسترداد السمات والمقاييس المخصّصة المحدّدة لموقع معيّن (getMetadata).
- ‫run_report: لتشغيل تقرير عادي في "إحصاءات Google" (runReport).
- ‫run_realtime_report: لتشغيل تقرير "الوقت الفعلي" في "إحصاءات Google" (runRealtimeReport).
- ‫run_funnel_report: لتشغيل تقرير استكشاف خطوات المستخدم في "إحصاءات Google" (runFunnelReport).
- ‫run_conversions_report: لتشغيل تقرير أداء الإحالات الناجحة (runConversionsReport).

نماذج الطلبات

بعد الربط، يمكنك طرح أسئلة على المساعد المستنِد إلى الذكاء الاصطناعي، مثل:

كم عدد المستخدمين الذين تم تسجيلهم أمس؟
ما هي منتجاتي الأكثر مبيعًا أمس؟
لديّ ميزانية تسويق تبلغ 5,000 دولار أمريكي شهريًا وأحتاج إلى تحقيق المزيد من الإيرادات. ساعدني في الإعداد خطة تسويق مستندة إلى البيانات.
ما هي السمات والمقاييس المخصّصة التي تم ضبطها في موقعي؟
ما هي الأحداث الأكثر رواجًا في موقعي على "إحصاءات Google" خلال آخر 90 يومًا؟

تحديد المشاكل وحلّها

استخدِم قائمة التحقّق التالية لحلّ الأخطاء الشائعة في الإعداد وأخطاء أثناء التشغيل:

403 PERMISSION_DENIED (واجهة برمجة التطبيقات غير مفعَّلة أو أذونات الموقع غير كافية):
- تأكَّد من تفعيل كلّ من Google Analytics Admin API (analyticsadmin.googleapis.com) وGoogle Analytics Data API (analyticsdata.googleapis.com) في المشروع المحدّد من قِبل GOOGLE_CLOUD_PROJECT.
- تأكَّد من أنّ المستخدم أو حساب الخدمة الذي تتم مصادقته لديه على الأقل دور المُشاهد (roles/analytics.viewer) في الموقع المستهدَف على "إحصاءات Google" في واجهة مستخدم "إحصاءات Google".
- إذا ظهرت رسالة الخطأ 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 API. اضبط "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):
- تأكَّد من تثبيت الإصدار 3.10 من Python أو إصدار أحدث (python3 --version).
- غالبًا لا تكتسب تطبيقات واجهة المستخدم الرسومية (GUI) على أجهزة الكمبيوتر المكتبي (مثل Claude Desktop وCursor) متغيّر البيئة PATH من واجهة المستخدم التفاعلية. استبدِل "pipx" أو "uvx" في "command" بالمسار الثنائي المطلق الذي يعرضه which pipx أو which uvx (على سبيل المثال، /opt/homebrew/bin/pipx أو /Users/username/.local/bin/pipx).