mcp-ga4

MCP-сервер для Google Analytics 4 — запуск отчетов, данные в реальном времени, пользовательские измерения и управление свойствами через Claude.

Возможности

• 9 инструментов, охватывающих отчетность, данные в реальном времени, пользовательские измерения/метрики, потоки данных и обратную связь

• Два режима конфигурации: одно свойство (переменные окружения) и мультиклиентский (config.json)

• Поддержка как сервисных аккаунтов, так и OAuth-учетных данных

• Поддержка относительных дат (today, yesterday, 7daysAgo, 30daysAgo, 90daysAgo)

• Построен на официальных Google SDK с паттернами устойчивости

Related MCP server: Google Analytics 4 MCP Server

Установка

npm install mcp-ga4

Или клонируйте репозиторий:

git clone https://github.com/mharnett/mcp-ga4.git
cd mcp-ga4
npm install
npm run build

Аутентификация

mcp-ga4 поддерживает два семейства учетных данных. Выбор детерминирован и происходит один раз при запуске: явный файл ключа / сервисный аккаунт имеет приоритет, затем пользовательский OAuth, а если ни один не настроен, сервер завершает работу с громкой ошибкой онбординга, называющей оба варианта. В коде нет встроенного пути к локальным учетным данным машины и нет тихого переключения во время выполнения — единственные входные данные для учетных данных — это переменные окружения и (опционально) ваш собственный config.json для каждого пользователя. (Поэтому последующая ошибка 403 отображается как ошибка API, а не как тихое переключение на другое семейство учетных данных.)

Приоритет: когда оба семейства настроены, файл ключа / сервисный аккаунт имеет приоритет над пользовательским OAuth.

Вариант A: Сервисный аккаунт (рекомендуется для автоматического / серверного использования)

Используйте это для любого постоянно работающего или серверного развертывания. Укажите GOOGLE_APPLICATION_CREDENTIALS (или credentials_file в config.json) на JSON-файл ключа. Сервисный аккаунт должен иметь доступ к свойству GA4 (Администрирование → Управление доступом к свойству → добавьте email сервисного аккаунта с как минимум Viewer). Токен обновления не требуется — сервер передает файл ключа напрямую в GA4 SDK:

GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

Файл ключа может быть настоящим ключом сервисного аккаунта или дампом OAuth-токена authorized_user — оба принимаются через опцию keyFile.

Вариант B: Пользовательский OAuth (личное / интерактивное использование)

Используйте это, если хотите, чтобы сервер действовал как пользователь Google пользователь (ваш собственный логин GA4). Вы приносите свой собственный Google OAuth-клиент и один раз создаете токен обновления.

1. В Google Cloud Console создайте OAuth 2.0 Client ID типа Desktop app. Включите Google Analytics Data API (и Admin API, если вы используете инструменты пользовательских измерений).

2. Экспортируйте свои учетные данные клиента и запустите помощник по токенам (использует PKCE, открывает браузер, выводит токен в stdout):

   export GA4_CLIENT_ID=...            # from the Desktop-app client
   export GA4_CLIENT_SECRET=...
   node get-refresh-token.cjs          # or: npm run auth

   Не перенаправляйте stdout этой команды в общий журнал — токен обновления выводится туда по замыслу.

3. Скопируйте выведенный GA4_REFRESH_TOKEN=... в ваше окружение. Во время выполнения сервер читает эти три переменные окружения:

   GA4_CLIENT_ID=...
   GA4_CLIENT_SECRET=...
   GA4_REFRESH_TOKEN=...

Запрашиваемая область видимости считывается из config.json oauth.scope (см. ниже), поэтому помощник и работающий сервер никогда не расходятся во мнениях о том, что вы предоставили.

Области видимости (минимальное предоставление)

Области видимости находятся в config.json в разделе oauth.scope. Зафиксированное значение по умолчанию:

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

analytics.edit требуется, потому что ga4_create_custom_dimension изменяет свойство через Admin API. Если вам нужен только доступ на чтение, переопределите oauth.scope в вашем собственном config.json на analytics.readonly и повторно запустите помощник.

Конфигурация

Безопасность: Никогда не делитесь своим файлом .mcp.json и не коммитьте его в git — он может содержать учетные данные API. Добавьте .mcp.json в ваш .gitignore.

Режим 1: Одно свойство (переменные окружения)

Установите ID свойства плюс одно из семейств аутентификации выше:

GA4_PROPERTY_ID=123456789
# then EITHER the OAuth trio (GA4_CLIENT_ID/SECRET/REFRESH_TOKEN)
# OR a service account: GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

Режим 2: Мультиклиентский (config.json)

Создайте config.json в корне проекта, чтобы сопоставить несколько свойств GA4 с каталогами проектов. Сервер автоматически определяет, какое свойство использовать, на основе рабочего каталога вызывающего. Учетные данные берутся из окружения (вариант A/B выше); config.json может дополнительно содержать путь к сервисному аккаунту credentials_file для конфигурации только с SA.

{
  "oauth": {
    "scope": "https://www.googleapis.com/auth/analytics.readonly https://www.googleapis.com/auth/analytics.edit"
  },
  "clients": {
    "client-a": {
      "name": "Client A",
      "folder": "/path/to/client-a/project",
      "property_id": "123456789"
    },
    "client-b": {
      "name": "Client B",
      "folder": "/path/to/client-b/project",
      "property_id": "987654321"
    }
  }
}

Использование

Claude Code (.mcp.json)

Режим одного свойства:

{
  "mcpServers": {
    "ga4": {
      "command": "npx",
      "args": ["mcp-ga4"],
      "env": {
        "GA4_PROPERTY_ID": "123456789",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
      }
    }
  }
}

Мультиклиентский режим:

{
  "mcpServers": {
    "ga4": {
      "command": "node",
      "args": ["/path/to/mcp-ga4/dist/index.js"]
    }
  }
}

Claude Desktop: Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows).

Типовые шаблоны запросов

Топ страниц: dimensions=pagePath, metrics=screenPageViews, order_by=screenPageViews

Источники трафика: dimensions=sessionSource,sessionMedium, metrics=sessions,totalUsers

Ежедневный тренд: dimensions=date, metrics=sessions,totalUsers

Эффективность кампании: dimensions=sessionCampaignName, metrics=sessions,conversions

Разбивка по устройствам: dimensions=deviceCategory, metrics=sessions,totalUsers

Инструменты

Форматы дат

Используйте YYYY-MM-DD для абсолютных дат или эти относительные сокращения:

• today

• yesterday

• 7daysAgo

• 30daysAgo

• 90daysAgo

Типовые измерения и метрики

Измерения: date, dateHour, eventName, pagePath, pageTitle, sessionSource, sessionMedium, sessionCampaignName, country, city, deviceCategory, browser, operatingSystem, landingPage, pageReferrer, newVsReturning, firstUserSource, firstUserMedium, firstUserCampaignName

Метрики: sessions, totalUsers, newUsers, activeUsers, screenPageViews, eventCount, conversions, engagedSessions, engagementRate, averageSessionDuration, bounceRate, sessionsPerUser, screenPageViewsPerSession, userEngagementDuration

Свежесть данных

• Стандартные отчеты: задержка 24-48 часов

• Отчеты в реальном времени: только последние 30 минут

Архитектура

Построен на:

• @google-analytics/data — GA4 Data API для отчетов

• @google-analytics/admin — GA4 Admin API для управления свойствами

• cockatiel — устойчивость (повторные попытки, автоматический выключатель)

• pino — структурированное логирование

Лицензия

MIT

Автор

Создано Марком Харнеттом / drak-marketing