كيف تبني خادم MCP لـ Google Analytics

خادم MCP لـ GA4 يعمل على حاسوبك المحمول هو عمل فترة بعد ظهر واحدة. أما خادم يستطيع أشخاص آخرون تسجيل الدخول إليه فمهمة أكبر بكثير. يقدّم لك هذا الدليل نسخة بعد الظهر، ثم يسرد ما تتطلبه النسخة الكبيرة، لتقرر أيهما تحتاج.

جدول المحتويات

تحقّق من الخادم الرسمي أولًا

تنشر Google خادم MCP خاصًا بـ Google Analytics، وما زال موسومًا بأنه تجريبي. يعمل على جهازك بلغة Python، وعليك تفعيل Google Analytics Admin API وData API في مشروع على Google Cloud قبل أن يعمل. يأتي جاهزًا بأدوات run_report وrun_realtime_report وrun_funnel_report، وأدوات للاستعلام عن حساباتك ومواقعك وأبعادك المخصصة وروابط Google Ads. إن كنت تحتاج GA4 وحده، وعلى جهازك فقط، فاستخدمه:

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

pipx run analytics-mcp

تشرح صفحة الإعداد من Google خطوات مشروع Cloud، وفي ملف README سطر claude mcp add الدقيق لـ Claude Code. لا توجد نسخة مستضافة، لذلك لا يعمل إلا حيث يمكنك تشغيل Python.

ابنِ خادمك الخاص عندما تريد أدوات مصممة على مقاس أسئلتك، أو بيانات من أكثر من مصدر في إجابة واحدة، أو خادمًا يستطيع فريقك أو عملاؤك استخدامه.

ما تحتاجه

• مشروع على Google Cloud مفعّل فيه Google Analytics Data API (خمس دقائق).
• معرّف عميل OAuth من نوع تطبيق سطح المكتب في المشروع نفسه، تنزّله بصيغة JSON. هذا هو الملف الذي يشير إليه --client-id-file.
• Node 22 أو أحدث، وهو ما تتطلبه الحزمة الحالية @google-analytics/data.
• صلاحية مُشاهد على موقع GA4، في حساب Google الذي ستسجّل الدخول به.

الخطوة 1: أداة واحدة تشغّل أي تقرير

ابدأ بأداة واحدة هي run_report. يعرف Claude أسماء مقاييس GA4 وأبعاده مسبقًا، لذلك تكفي أداة مرنة واحدة لمعظم الأسئلة. قسّمها لاحقًا إلى أدوات أضيق، عندما ترى الأسئلة التي تطرحها فعلًا.

جهّز المجلد وسجّل الدخول مرة واحدة. أمر gcloud الثاني مهم: ترفض واجهات Analytics البرمجية من Google بيانات اعتماد المستخدم التي لا تحدد مشروعًا للحصة.

mkdir ga4-mcp && cd ga4-mcp
npm init -y && npm pkg set type=module
npm install @modelcontextprotocol/sdk @google-analytics/data zod

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
gcloud auth application-default set-quota-project YOUR_PROJECT_ID

ثم احفظ هذا باسم ga4.ts:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { BetaAnalyticsDataClient } from '@google-analytics/data';
import { z } from 'zod';

const ga = new BetaAnalyticsDataClient(); // Application Default Credentials
const server = new McpServer({ name: 'ga4', version: '1.0.0' });

server.registerTool(
  'run_report',
  {
    description:
      'Run a GA4 report. Uses GA4 Data API metric and dimension names. ' +
      'Dates accept YYYY-MM-DD, "28daysAgo", "yesterday", "today".',
    inputSchema: {
      propertyId: z.string().describe('Numeric GA4 property ID, e.g. 123456789'),
      metrics: z.array(z.string()).describe('e.g. ["sessions", "engagedSessions"]'),
      dimensions: z.array(z.string()).default([]).describe('e.g. ["sessionDefaultChannelGroup"]'),
      startDate: z.string().default('28daysAgo'),
      endDate: z.string().default('today'),
    },
  },
  async ({ propertyId, metrics, dimensions, startDate, endDate }) => {
    const [res] = await ga.runReport({
      property: `properties/${propertyId}`,
      dateRanges: [{ startDate, endDate }],
      metrics: metrics.map((name) => ({ name })),
      dimensions: dimensions.map((name) => ({ name })),
      limit: 100,
    });
    // Turn GA's nested rows into plain { dimension: value, metric: value } objects.
    const rows = (res.rows ?? []).map((row) => {
      const out: Record<string, string> = {};
      row.dimensionValues?.forEach((v, i) => (out[dimensions[i]] = v.value ?? ''));
      row.metricValues?.forEach((v, i) => (out[metrics[i]] = v.value ?? ''));
      return out;
    });
    return { content: [{ type: 'text', text: JSON.stringify({ rowCount: res.rowCount, rows }) }] };
  },
);

await server.connect(new StdioServerTransport());

لا يوجد أي مفتاح في الملف. يستخدم العميل تسجيل الدخول الذي حفظه gcloud للتو، وكل استدعاء يعمل باسمك وبصلاحية المُشاهد التي لديك.

الخطوة 2: أضفه إلى Claude

في Claude Code، يسجّله أمر واحد. استخدم المسار الكامل للملف. يجعل --scope user الخادم متاحًا في كل مشاريعك؛ ومن دونه لا يُحمَّل إلا في المجلد الذي شغّلت فيه الأمر:

claude mcp add --scope user ga4 -- npx -y tsx /full/path/to/ga4-mcp/ga4.ts

ثم اسأل: “في الموقع 123456789، ما القنوات التي جلبت أكبر عدد من الجلسات المتفاعلة الشهر الماضي؟” يختار Claude المقاييس ويستدعي الأداة ويشرح لك الصفوف. في Claude Desktop يوضع الخادم نفسه في ملف الإعدادات بدلًا من ذلك، ويوضح دليلي لبناء أول خادم MCP مكان هذا الملف.

الخطوة 3: حيث تبدأ الصعوبة

كل ما سبق يعمل باسمك وعلى جهازك. هذا ما يتغير عندما يجب أن يعمل في أي مكان آخر:

1. الاستضافة وOAuth. لا يستطيع claude.ai ولا تطبيق الهاتف الوصول إلى خادم على حاسوبك المحمول. يحتاج الخادم المستضاف إلى تدفق OAuth الخاص بـ MCP، كي يسجّل كل مستخدم الدخول إلى حسابه في Google، وإلى مكان آمن لحفظ رموز التحديث الخاصة بهم.
2. تحقق Google من التطبيق. analytics.readonly نطاق حساس. إلى أن تتحقق Google من تطبيقك، يرى كل مستخدم تحذير “تطبيق لم يتم التحقق منه”، ويكون الحد الأقصى 100 مستخدم. يتطلب التحقق سياسة خصوصية على نطاقك الخاص، وفيديو توضيحيًا لتسجيل الدخول، ومبررًا مكتوبًا لكل نطاق، ومراجعة.
3. الحصص. تحسب Data API الرموز لكل موقع: 40,000 في الساعة و200,000 في اليوم للموقع العادي، ولا يتجاوز أي مشروع على Cloud 14,000 في الساعة لكل موقع، مع 10 طلبات متزامنة كحد أقصى. تكلّف معظم الطلبات 10 رموز أو أقل. لكن الفترات الطويلة والأبعاد الكثيرة والمواقع ذات الزيارات الكبيرة تكلّف أكثر، والوكيل يطلق التقارير أسرع بكثير من شخص ينقر في واجهة GA4. عند الاستضافة يُخصم كل استدعاء من حصة مشروعك، لذا أضف returnPropertyQuota: true لترى كلفة كل طلب، وخزّن مؤقتًا ما يتكرر، وأبقِ التقارير صغيرة.

يتولى SiteWide الاستضافة وتسجيل الدخول. ما زال تحقق Google منه قيد التنفيذ، لذلك يعرض GA4 هناك أيضًا شاشة التطبيق غير المتحقق منه نفسها في الوقت الحالي. إن كنت تفضّل ألا تبني أيًا من هذا، فاربط SiteWide بدلًا من ذلك.

اطلب من Claude أن يبنيه

الصق هذا في Claude Code داخل مجلد فارغ. الطلب بالإنجليزية لأن الكود بالإنجليزية أيضًا:

Build me a TypeScript MCP server for Google Analytics 4 using @modelcontextprotocol/sdk and @google-analytics/data. Give it one tool, run_report, that takes a property id, metrics, dimensions and a date range. Authenticate with Application Default Credentials. Then give me the exact gcloud command to log in with the analytics.readonly scope, and register the server with `claude mcp add`. Don't invent metric names: link me to Google's API schema page so I can check them.

قبل أن تثق بالنتيجة، راجع كل مقياس وبُعد يستخدمه في صفحة مخطط API من Google. الاسم المختلق يبدو سليمًا في الكود، ولا يفشل إلا عندما ترفضه الواجهة البرمجية.