GA4 MCP Server

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

Это первый коннектор в более крупной платформе. Общая инфраструктура (аутентификация, клиенты, хранилище токенов Google OAuth, авторизация, логирование, ошибки) переиспользуется. Код, специфичный для GA4, находится в src/connectors/ga4 и src/mcp/ga4. Не рассматривайте это как монолитный Google Marketing MCP.

Архитектура

Claude
  |  MCP OAuth 2.1 + Streamable HTTP
  v
Next.js / Vercel  (/mcp)
  |-- MCP tools (ga4_*)
  |-- Authorization (client_members only)
  |-- GA4 service
  |-- Google OAuth token manager
  v
Supabase
  |-- clients
  |-- client_members   (application identity)
  |-- google_connections (Google credential, not app identity)
  |-- ga4_properties

Пользователи приложения — это пользователи Supabase Auth. Доступ к тенанту осуществляется только через client_members(user_id, client_id, role). Учетная запись, подключенная к Google, — это учетные данные, принадлежащие клиенту, и никогда не является пользователем приложения.

Локальная настройка

npm install
cp .env.example .env.local
# fill in the values documented below
npx supabase start   # or link a remote project
npx supabase db reset --local
npm run dev

Откройте http://localhost:3000, создайте учетную запись приложения, создайте клиента, затем подключите Google Analytics.

Настройка Google Cloud

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

2. Включите Google Analytics Data API и Google Analytics Admin API.

3. Настройте экран согласия OAuth (External или Internal).

4. Создайте учетные данные OAuth 2.0 Client ID (Веб-приложение).

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

   • Локально: http://localhost:3000/api/auth/google/callback

   • Продакшен: https://<ваш-домен>/api/auth/google/callback

6. Запрашивайте только области GA4:

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

   • openid

   • email

Не добавляйте области DV360 или Google Ads в этот коннектор.

Настройка GA4

1. Войдите в это приложение с помощью email/пароля (идентификация приложения).

2. Создайте клиента (вы становитесь owner в client_members).

3. При желании добавьте других пользователей приложения как owner или member.

4. Нажмите Connect Google Analytics. Это привязывает учетные данные Google к клиенту.

5. Привяжите одну или несколько учетных записей GA4, обнаруженных в этой учетной записи Google.

Участник, который не нажал Connect, все равно может выполнять запросы к клиенту, если у него есть строка в client_members.

Настройка Supabase

Этот репозиторий включает SQL-миграции в supabase/migrations. Создавайте их с помощью CLI; не придумывайте имена файлов.

Локально:

npx supabase start
npx supabase db reset --local

Удаленно:

npx supabase link --project-ref <project-ref>
npx supabase db push

Ключ роли службы предназначен только для сервера. Никогда не раскрывайте SUPABASE_SERVICE_ROLE_KEY или токены обновления Google в браузере.

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

См. .env.example. Обязательные:

Не помещайте идентификатор учетной записи GA4 в .env. Учетные записи принадлежат клиентам в Supabase.

Сгенерируйте ключ шифрования токенов:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Настройка MCP (Claude)

Удаленная конечная точка:

https://<your-domain>/mcp

Этот сервер реализует MCP OAuth 2.1:

• Метаданные защищенного ресурса: /.well-known/oauth-protected-resource

• Метаданные сервера авторизации: /.well-known/oauth-authorization-server

• Авторизация: /oauth/authorize (вход в приложение + согласие)

• Токен: /oauth/token (authorization_code + refresh_token, PKCE S256)

• Регистрация: /oauth/register (запасной вариант DCR)

• CIMD рекламируется (client_id_metadata_document_supported)

В Claude: Settings → Connectors → Add custom connector → вставьте https://<ваш-домен>/mcp. Claude выполнит OAuth. После вашего одобрения инструменты станут доступны.

Локальный инспектор:

npx @modelcontextprotocol/inspector

Подключитесь с помощью Streamable HTTP к http://localhost:3000/mcp. Вам все равно понадобится действительный токен MCP Bearer из потока OAuth.

Инструменты

Каждый инструмент требует client_id. Инструменты, ограниченные учетной записью, также требуют связанный property_id. Авторизация всегда проверяет client_members перед вызовом Google.

Пример: ga4_run_report

{
  "client_id": "11111111-1111-1111-1111-111111111111",
  "property_id": "123456789",
  "date_start": "2026-08-01",
  "date_end": "2026-08-15",
  "dimensions": ["country"],
  "metrics": ["activeUsers", "sessions", "totalRevenue"],
  "limit": 10
}

Пример: ga4_compare_periods

{
  "client_id": "11111111-1111-1111-1111-111111111111",
  "property_id": "123456789",
  "current_start": "2026-08-01",
  "current_end": "2026-08-15",
  "previous_start": "2026-07-17",
  "previous_end": "2026-07-31",
  "metrics": ["activeUsers", "sessions", "totalRevenue"]
}

Затем Claude может отвечать на такие вопросы, как:

• Сколько пользователей было вчера?

• Топ-10 стран в этом месяце

• Сравните этот месяц с прошлым

• Сколько активных пользователей сейчас на сайте?

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

npm test

Тесты используют имитированные Google и Supabase. Они никогда не используют продакшен-токены OAuth.

Vercel

Разверните приложение Next.js и установите те же переменные окружения. MCP_BASE_URL и GOOGLE_REDIRECT_URI должны использовать продакшен-домен. Маршрут /mcp работает на среде выполнения Node.js с максимальной продолжительностью 60 секунд.

Структура проекта

src/
  auth/              application authentication
  authorization/     authorizeClient via client_members
  oauth/             Google OAuth + token manager
  mcp-oauth/         MCP OAuth 2.1 authorization server
  connectors/ga4/    Google Analytics APIs
  mcp/ga4/           MCP tools
  repositories/      Supabase data access
  app/mcp/           Streamable HTTP transport

Будущие коннекторы (DV360, Google Ads) должны добавлять src/connectors/<имя> и src/mcp/<имя> и переиспользовать общее ядро. Не создавайте универсальное хранилище для Google API.