Как создать 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 важна: API 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, и надёжное место для хранения их refresh-токенов.
2. Проверка приложения в Google. analytics.readonly — чувствительный scope. Пока Google не проверит ваше приложение, каждый пользователь видит предупреждение о непроверенном приложении, а вы ограничены 100 пользователями. Для проверки нужны политика конфиденциальности на вашем собственном домене, демо-видео входа, письменное обоснование для каждого scope и рассмотрение заявки.
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. Выдуманное название в коде выглядит нормально и ломается только тогда, когда API его отклоняет.