GA4 Analytics MCP V2

Мультиоператорский коннектор Google Analytics 4 для Claude.ai Custom Connectors, размещённый на Google Cloud Run.

Это версия 2. Она является отдельным приложением от V1. Не используйте повторно секреты V1, OAuth-клиенты, сервисы Cloud Run или удалённые Git-репозитории.

Operator A or Operator B
  → same Claude Custom Connector URL
  → https://<v2-host>/mcp
  → MCP OAuth (Claude → V2)
  → Google OAuth (operator's own Google account)
  → operator credentials + active GA4 property in Firestore
  → GA4 Admin / Data APIs

Здесь нет локального stdio-сервера и нет Supabase.

Архитектура

Связаны два уровня OAuth:

1. Claude → V2: MCP OAuth 2.1 (метаданные защищённого ресурса, DCR, CIMD, PKCE).

2. V2 → Google: вход в Google происходит внутри MCP authorize. sub токена доступа MCP — это субъект (sub) учётной записи Google. Email используется только для отображения.

Каждый оператор имеет:

• собственный зашифрованный Google refresh-токен

• собственный список доступных ресурсов GA4 (из Google Admin API)

• собственный сохранённый активный ресурс

Оператор A не может использовать учётные данные Google оператора B или выбрать ресурс, к которому учётная запись Google A не имеет доступа.

Инструменты MCP

Инструменты отчётов используют сохранённый активный ресурс, если propertyId не указан. Переданный propertyId принимается только в том случае, если аутентифицированная учётная запись Google имеет к нему доступ, и затем он становится новым активным ресурсом.

Локальная разработка

cd D:\MCP_Servers\Ga4McpV2
npm install
copy .env.example .env.local

Заполните .env.local значениями V2. Не копируйте секреты V1.

Необязательный эмулятор Firestore:

gcloud emulators firestore start --host-port=localhost:8080

Установите FIRESTORE_EMULATOR_HOST=localhost:8080 и FIRESTORE_PROJECT_ID в .env.local.

npm run dev
npm test
npm run build

• Приложение: http://localhost:3000

• MCP: http://localhost:3000/mcp

• Health: http://localhost:3000/health

• Google callback: http://localhost:3000/oauth/google/callback

Claude.ai не может получить доступ к localhost. Разверните V2 в Cloud Run перед добавлением Custom Connector.

Переменные окружения

V2 не использует GOOGLE_REFRESH_TOKEN или MCP_AUTH_TOKEN.

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

По возможности используйте новый проект Google Cloud. Если вы используете общий проект с V1, всё равно создайте отдельные сервис Cloud Run, репозиторий Artifact Registry, OAuth-клиент и секреты.

Включите:

• Cloud Run

• Cloud Build

• Artifact Registry

• Firestore

• Secret Manager

• Google Analytics Admin API

• Google Analytics Data API

Предлагаемые имена ресурсов (заполнители — замените на ваш проект):

• Сервис Cloud Run: ga4-mcp-v2

• Artifact Registry: ga4-mcp-v2

• Коллекция Firestore: operators

Сервисный аккаунт Cloud Run должен иметь:

• roles/datastore.user для базы данных Firestore V2

• roles/secretmanager.secretAccessor только для секретов V2

Не предоставляйте сервисному аккаунту права администратора Secret Manager или доступ к секретам V1.

Google OAuth-клиент (только V2)

Создайте новое OAuth Web-приложение. Не редактируйте клиент V1.

Экран согласия:

• Тип пользователя: External (или Internal для Workspace-only)

• Название приложения: что-то вроде GA4 MCP Connector V2

• Области доступа:

  • openid

  • email

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

• Добавляйте тестовых пользователей, пока приложение находится в статусе Testing

• Публикация обязательна для не тестовых пользователей, поскольку области доступа Analytics являются чувствительными

Авторизованный URI перенаправления:

https://<v2-cloud-run-url>/oauth/google/callback

Локально:

http://localhost:3000/oauth/google/callback

Claude Custom Connector

1. Разверните V2 и установите APP_BASE_URL в URL Cloud Run.

2. В Claude добавьте Custom Connector.

3. URL: https://<v2-host>/mcp

4. Каждый оператор выполняет вход в Google из своей собственной учётной записи Claude.

5. Если у учётной записи Google несколько ресурсов GA4, они выбирают один. Этот выбор сохраняется, пока они не переключатся.

Тестирование

npm test

Модульные тесты покрывают:

• Метаданные MCP OAuth, DCR, PKCE и привязанный к Google JWT sub

• Изоляция операторов (учётные данные и списки разрешённых ресурсов)

• Постоянный активный ресурс

• Обновление / ротация токенов

• Отозванные разрешения Google

• Маскирование структурированных логов

Реальные учётные данные V1 не используются.

Развёртывание (не запускайте, пока не запрошено)

Только документация. Развёртывание V1 должно остаться нетронутым.

.\scripts\cloud-run-setup.ps1 -ProjectId YOUR_V2_PROJECT_ID
.\scripts\cloud-run-deploy.ps1 -ProjectId YOUR_V2_PROJECT_ID
.\scripts\cloud-run-set-env.ps1 `
  -ProjectId YOUR_V2_PROJECT_ID `
  -AppBaseUrl https://YOUR_V2_CLOUD_RUN_URL `
  -GoogleClientId YOUR_V2_CLIENT_ID `
  -GoogleClientSecret YOUR_V2_CLIENT_SECRET `
  -McpTokenSecret YOUR_MCP_TOKEN_SECRET `
  -OauthStateSecret YOUR_OAUTH_STATE_SECRET `
  -TokenEncryptionKey YOUR_TOKEN_ENCRYPTION_KEY

При подключении сервиса предпочитайте ссылки на Secret Manager для продакшен-секретов вместо значений переменных окружения в открытом виде.

После развёртывания:

1. Добавьте URI обратного вызова Cloud Run в OAuth-клиент V2.

2. Убедитесь, что Firestore создан в режиме Native.

3. Добавьте https://<v2-host>/mcp в Claude.

Вопросы безопасности

• Refresh-токены шифруются с помощью AES-256-GCM перед записью в Firestore.

• Инструменты MCP никогда не возвращают access-токены, refresh-токены или коды авторизации.

• Журналы маскируют токены, секреты, cookies и коды авторизации.

• Идентификаторы ресурсов от Claude проверяются по актуальному списку Admin API для этого оператора.

• Инструменты завершаются отказом (fail closed), если к запросу не привязан контекст оператора.

• Только HTTPS-cookies в продакшене.

Git

Этот репозиторий предназначен только для V2. remote V1 — git@github.com:devopsbrandmirchi/Ga4McpServer.git, и его никогда нельзя добавлять сюда. Создайте новый репозиторий GitHub, когда будете готовы опубликовать V2.