GA4 Analytics MCP

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

Claude.ai Custom Connector
  → https://ga4-mcp-xxxxx-uc.a.run.app/ga4mcp
  → Cloud Run
  → Google Analytics Data API
  → your GA4 properties

Локального stdio-сервера нет, не требуется npx и нет claude_desktop_config.json.

Два уровня аутентификации остаются раздельными:

1. Claude → MCP: MCP OAuth (CIMD / DCR)

2. MCP → Google: Google OAuth refresh token, хранящийся в GOOGLE_REFRESH_TOKEN

MCP-инструменты

Related MCP server: Google Analytics MCP Server

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

npm install
copy .env.example .env.local

Заполните .env.local, затем:

npm run dev

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

• MCP: http://localhost:3000/ga4mcp

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

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

npm test
npm run build

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

Настройка Google Cloud (один проект)

Используйте один и тот же проект Google Cloud для API, OAuth и Cloud Run.

1. Установка и вход

1. Установите Google Cloud SDK.

2. Выполните:

gcloud auth login
gcloud auth application-default login

3. Создайте или выберите проект в Google Cloud Console.

gcloud config set project YOUR_PROJECT_ID

2. Включение API

.\scripts\cloud-run-setup.ps1 -ProjectId YOUR_PROJECT_ID -Region us-central1

Это включает:

• Cloud Run

• Cloud Build

• Artifact Registry

• Google Analytics Data API

• Google Analytics Admin API

Или включите их в консоли: APIs & Services → Library.

3. Согласие OAuth и веб-клиент

Этот клиент Google OAuth нужен только для того, чтобы Cloud Run мог читать ваши данные GA4. Это не клиент для расширенных настроек Claude.ai.

1. Откройте APIs & Services → OAuth consent screen.

2. Тип пользователя: External для личного Gmail-аккаунта.

3. Название приложения: GA4 MCP.

4. Добавьте себя как тестового пользователя, если остаётесь в режиме тестирования.

5. Опубликуйте в Production, чтобы токены обновления не истекали через 7 дней.

6. Создайте учётные данные OAuth client ID.

7. Тип приложения: Web application.

8. Авторизованные URI перенаправления (добавьте оба):

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

   • https://ga4-mcp-XXXXXXXX-uc.a.run.app/oauth/google/callback
     (используйте реальный URL Cloud Run после первого развёртывания)

9. Область доступа, используемая этим приложением:

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

10. Скопируйте ID клиента и секрет клиента. Не сохраняйте их в Git.

Google-аккаунт, который вы авторизуете, должен уже иметь доступ к свойствам GA4, которые Claude должен запрашивать.

Развёртывание на Cloud Run

Имя службы по умолчанию: ga4-mcp. Регион по умолчанию: us-central1.

.\scripts\cloud-run-deploy.ps1 -ProjectId YOUR_PROJECT_ID -Region us-central1

Скрипт выводит:

https://ga4-mcp-XXXXXXXX-uc.a.run.app
https://ga4-mcp-XXXXXXXX-uc.a.run.app/ga4mcp
https://ga4-mcp-XXXXXXXX-uc.a.run.app/health
https://ga4-mcp-XXXXXXXX-uc.a.run.app/oauth/google/callback

Служба разворачивается с разрешением неаутентифицированного доступа. Это обязательно. Claude.ai подключается от Anthropic (160.79.104.0/21). Аутентификация — MCP_AUTH_TOKEN / MCP OAuth, а не Cloud Run IAM.

Установка переменных окружения

.\scripts\cloud-run-set-env.ps1 `
  -ProjectId YOUR_PROJECT_ID `
  -AppBaseUrl "https://ga4-mcp-XXXXXXXX-uc.a.run.app" `
  -GoogleClientId "....apps.googleusercontent.com" `
  -GoogleClientSecret "...." `
  -McpAuthToken "a-long-random-string"

Затем добавьте URL обратного вызова Cloud Run в клиент Google OAuth, если вы ещё этого не сделали.

Подключение Google

1. Откройте https://ga4-mcp-XXXXXXXX-uc.a.run.app/oauth/google

2. Введите MCP_AUTH_TOKEN

3. Войдите в свой Google-аккаунт

4. Скопируйте GOOGLE_REFRESH_TOKEN со страницы успеха

5. Установите его и дайте Cloud Run запустить новую ревизию:

.\scripts\cloud-run-set-env.ps1 `
  -ProjectId YOUR_PROJECT_ID `
  -AppBaseUrl "https://ga4-mcp-XXXXXXXX-uc.a.run.app" `
  -GoogleClientId "....apps.googleusercontent.com" `
  -GoogleClientSecret "...." `
  -McpAuthToken "a-long-random-string" `
  -GoogleRefreshToken "1//...."

Cloud Run не может записывать переменные окружения изнутри контейнера. То же правило, что и для любого серверного хостинга.

Проверка службы

https://ga4-mcp-XXXXXXXX-uc.a.run.app/health

должен вернуть:

{"status":"ok"}

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

Установите их в службе Cloud Run. Не помещайте их в Git.

Опциональный путь в консоли: Cloud Run → ga4-mcp → Edit & deploy new revision → Variables & secrets.

Custom Connector в Claude.ai

1. Убедитесь, что /health возвращает {"status":"ok"}.

2. Завершите Google OAuth и установите GOOGLE_REFRESH_TOKEN.

3. В Claude.ai откройте Customize → Connectors → Add custom connector.

4. Имя: GA4 Analytics

5. URL:

https://ga4-mcp-XXXXXXXX-uc.a.run.app/ga4mcp

6. Оставьте Advanced OAuth Client ID / Secret пустыми.

7. Нажмите Add.

8. Включите коннектор в + → Connectors.

9. При первом вызове инструмента GA4 появится Connect. Введите MCP_AUTH_TOKEN на странице согласия этого приложения (не ваш пароль Google).

10. Спросите: Сколько у меня было пользователей вчера?

Ручная работа с gcloud (если вы не хотите использовать скрипты)

gcloud artifacts repositories create ga4-mcp --repository-format=docker --location=us-central1
gcloud builds submit --config cloudbuild.yaml --substitutions=_REGION=us-central1
gcloud run services describe ga4-mcp --region us-central1 --format="value(status.url)"
gcloud run services update ga4-mcp --region us-central1 --update-env-vars APP_BASE_URL=https://...,GOOGLE_CLIENT_ID=...,GOOGLE_CLIENT_SECRET=...,GOOGLE_REDIRECT_URI=https://.../oauth/google/callback,MCP_AUTH_TOKEN=...

Безопасность

• Никогда не логируйте токены Google, коды авторизации, секреты клиентов или MCP JWT.

• MCP-инструменты никогда не возвращают секреты.

• Сохраняется только GOOGLE_REFRESH_TOKEN как переменная окружения Cloud Run.

• Входящий трафик Cloud Run является публичным, чтобы Claude мог подключаться. Не ставьте дополнительный вход Cloud IAP / IAM перед /ga4mcp.

• Сгенерируйте длинный случайный MCP_AUTH_TOKEN.

Даты

Передаются в GA4 без изменений: today, yesterday, 7daysAgo, 30daysAgo, 90daysAgo или YYYY-MM-DD. Измерение date возвращается в формате YYYYMMDD.

Известные ограничения

• Один Google-аккаунт и один токен обновления.

• Cloud Run не может сохранять файлы или изменять переменные окружения во время выполнения; установите GOOGLE_REFRESH_TOKEN и разверните новую ревизию.

• Токены обновления в режиме тестирования Google истекают примерно через 7 дней.

• Данные в реальном времени охватывают примерно последние 30 минут.

• Размер отчёта ограничен 10 000 строк.

• Холодный старт может добавлять несколько секунд, когда min-instances равно 0.

Файлы, добавленные для Cloud Run