GA4 Analytics MCP

Персональный коннектор Google Analytics 4 для пользовательских коннекторов Claude.ai. Один аккаунт Google, один MCP-сервер, развёрнутый на Vercel.

Claude.ai Custom Connector
  → https://<VERCEL_PROJECT_NAME>.vercel.app/ga4mcp
  → Vercel Streamable HTTP MCP
  → Google Analytics Data API
  → your GA4 properties

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

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

1. Claude → MCP: MCP OAuth (CIMD / DCR / опциональный клиент Advanced Settings)

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

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

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

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. Разверните проект на Vercel перед добавлением пользовательского коннектора.

Настройка Google Cloud

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

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

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

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

4. Настройте экран согласия OAuth (External для личного Gmail). Опубликуйте в Production, чтобы refresh-токены не истекали через 7 дней.

5. Создайте OAuth-клиент Web application.

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

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

   • https://<VERCEL_PROJECT_NAME>.vercel.app/oauth/google/callback

7. Область (scope), используемая этим приложением:

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

8. Скопируйте идентификатор клиента и секрет в переменные окружения.

Затем перейдите по адресу /oauth/google, введите MCP_AUTH_TOKEN и войдите в аккаунт Google, которому принадлежат ваши ресурсы GA4.

• Локально refresh-токен записывается в .env.local.

• На Vercel вставьте GOOGLE_REFRESH_TOKEN в переменные окружения проекта и выполните повторный деплой.

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

Vercel

npm i -g vercel
vercel
vercel --prod

Добавьте переменные окружения в проект Vercel. После первого Google OAuth на продакшене установите GOOGLE_REFRESH_TOKEN и выполните повторный деплой.

Отключите Deployment Protection / Vercel Authentication на продакшене. Claude.ai подключается из сети Anthropic (160.79.104.0/21). Если перед /ga4mcp стоит Vercel SSO, коннектор не сможет подключиться.

Продакшен-URL:

https://<VERCEL_PROJECT_NAME>.vercel.app/ga4mcp
https://<VERCEL_PROJECT_NAME>.vercel.app/oauth/google/callback
https://<VERCEL_PROJECT_NAME>.vercel.app/health

Пользовательский домен можно добавить позже. Продолжайте использовать APP_BASE_URL, чтобы не менять код.

Пользовательский коннектор Claude.ai

1. Разверните проект на Vercel и убедитесь, что https://<VERCEL_PROJECT_NAME>.vercel.app/health возвращает {"status":"ok"}.

2. Подключите Google по адресу https://<VERCEL_PROJECT_NAME>.vercel.app/oauth/google.

3. Поместите GOOGLE_REFRESH_TOKEN в переменные окружения Vercel и выполните повторный деплой.

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

5. Название: GA4 Analytics

6. URL:

   https://<VERCEL_PROJECT_NAME>.vercel.app/ga4mcp

7. Оставьте Advanced OAuth Client ID / Secret пустыми. Claude использует CIMD для работы с конечными точками авторизации этого сервера.

8. Нажмите Add.

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

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

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

initialize и tools/list являются публичными, чтобы Claude мог обнаружить инструменты. tools/call возвращает HTTP 401 с заголовком WWW-Authenticate до завершения MCP OAuth.

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

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

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

• Токены доступа Google не хранятся; в переменных окружения сохраняется только GOOGLE_REFRESH_TOKEN.

• Не помещайте секреты в Git.

Даты

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

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

• Один аккаунт Google и один refresh-токен.

• Vercel не может записывать переменные окружения во время выполнения; вставьте GOOGLE_REFRESH_TOKEN и выполните повторный деплой.

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

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

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

• Я не могу завершить живой процесс подключения Claude.ai из этого репозитория; для этого нужны ваши аккаунты Claude и Vercel.