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

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

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

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

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

  1. ثبِّت Python وأداة تشغيل الحِزم:

  2. فعِّل Google Analytics APIs في :

  3. منح إذن الوصول إلى موقع على "إحصاءات Google":

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

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

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

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

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

  1. ثبِّت gcloud CLI وافتحه.

  2. شغِّل 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

  3. عند انتهاء الأمر، انسخ مسار بيانات الاعتماد المطبوع على وحدة التحكّم (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

  1. ثبِّت Antigravity CLI أو Antigravity IDE.

  2. أضِف خادم 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"
      }
    }
  }
}

  3. تأكَّد من أنّ "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 بمهارات وكيل الذكاء الاصطناعي في "إحصاءات Google". تتضمّن مجموعة المهارات مهارات google-analytics-data-api-basics وgoogle-analytics-admin-api-basics لـ Google Analytics Data API وGoogle Analytics Admin API.

ثبِّت المهارات في دليل مشروعك باستخدام الأمر npx (يتطلّب Node.js)، أو اطّلِع على مهارات وكيل الذكاء الاصطناعي في "إحصاءات Google" للتعرّف على خيارات Google Antigravity وClaude Code وCodex وCursor:

npx skills add google/skills/skills/analytics

أدوات 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).

الخطوات التالية