Google Analytics MCP Server — подключение GA4 к агентному слою

Практический справочник по Google Analytics MCP Server: как дать MCP-клиенту доступ к отчётам GA4, какие инструменты доступны, как настроить права и как проверить подключение.

Что представляет собой Google Analytics MCP Server

Google Analytics MCP Server — официальный экспериментальный MCP-сервер с открытым исходным кодом, размещённый в организации googleanalytics на GitHub. Он передаёт языковой модели инструменты для чтения данных Google Analytics.[1][2]

Сервер распространяется под лицензией Apache 2.0 и запускается локально. Его границы определены явно:

• поддерживаются запросы на чтение;
• настройки и конфигурация Google Analytics не редактируются;
• состав инструментов и порядок установки могут меняться, пока проект имеет статус Experimental.

По актуальному README доступны следующие инструменты:

• get_account_summaries — получение списка доступных аккаунтов и свойств;
• get_property_details — сведения о выбранном свойстве;
• list_google_ads_links — список связей свойства с аккаунтами Google Ads;
• run_report — обычный отчёт через Data API;
• run_funnel_report — отчёт по воронке;
• run_realtime_report — отчёт в реальном времени;
• get_custom_dimensions_and_metrics — пользовательские параметры и показатели свойства.

run_funnel_report обращается к методу Data API v1alpha. В официальном обзоре Google runFunnelReport обозначен как Early preview, поэтому при обновлении сервера для этого сценария особенно вероятны несовместимые изменения.[3]

Как устроено подключение

• GA4 хранит данные и определяет доступ пользователя или сервисного аккаунта.
• Google Analytics MCP Server обращается к Admin API и Data API.
• MCP-клиент запускает сервер и передаёт ему запросы агента.
• Агент выбирает инструмент, формирует параметры отчёта и объясняет результат.

API возвращает данные с учётом выбранной в свойстве модели идентификации пользователей, включая Blended, Observed и Device-based. Поэтому два свойства с разными настройками Reporting Identity могут показывать разные пользовательские показатели даже для похожих запросов.[3]

Что подготовить перед установкой

Понадобятся:

1. Свойство GA4 с накопленными данными.
2. Пользовательская учётная запись или сервисный аккаунт с доступом к этому свойству.
3. Проект Google Cloud.
4. Включённые Google Analytics Admin API и Google Analytics Data API.
5. Python и pipx.
6. MCP-клиент, способный запускать локальный сервер, например Gemini CLI, Gemini Code Assist или Claude Code.

Настройка учётных данных

Актуальная инструкция репозитория использует Application Default Credentials (ADC) — стандартный механизм Google Cloud для предоставления приложению учётных данных.

Учётные данные должны включать область доступа Google Analytics только для чтения:

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

В командах ниже к этой области также добавляется cloud-platform.

Пользовательская авторизация OAuth

Этот вариант подходит для персональной работы. После создания OAuth-клиента и загрузки его JSON-файла выполните:

gcloud auth application-default login --scopes https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform --client-id-file=YOUR_CLIENT_JSON_FILE

Имперсонация сервисного аккаунта

Для серверного или командного контура можно настроить ADC через имперсонацию отдельного сервисного аккаунта:

gcloud auth application-default login --impersonate-service-account=SERVICE_ACCOUNT_EMAIL --scopes=https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform

Сервисный аккаунт должен иметь доступ к нужному свойству GA4. После завершения команды gcloud сохраните путь, указанный в строке Credentials saved to file: он понадобится в конфигурации MCP-клиента.

Запуск сервера в MCP-клиенте

Сервер запускается через пакет analytics-mcp:

pipx run analytics-mcp

Gemini CLI или Gemini Code Assist

Добавьте сервер в mcpServers, указав путь к ADC и идентификатор проекта:

{
  "mcpServers": {
    "analytics-mcp": {
      "command": "pipx",
      "args": ["run", "analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID"
      }
    }
  }
}

Claude Code

Официальный README предлагает добавить сервер командой:

claude mcp add analytics-mcp --scope user -e "GOOGLE_APPLICATION_CREDENTIALS=PATH_TO_CREDENTIALS_JSON" -e "GOOGLE_PROJECT_ID=YOUR_PROJECT_ID" -- pipx run analytics-mcp

Не помещайте файл учётных данных в репозиторий и не передавайте его содержимое в промптах.

Проверка результата

После настройки выполните минимальную проверку:

1. Откройте список MCP-серверов в клиенте. В Gemini CLI и Gemini Code Assist для этого используется команда /mcp.
2. Убедитесь, что в списке присутствует analytics-mcp.
3. Запросите сведения о доступном свойстве, например: «Покажи мои аккаунты и свойства Google Analytics».
4. Затем выполните простой отчёт: «Сколько пользователей было вчера в свойстве X?».

Успешное подключение подтверждают два наблюдаемых результата:

• клиент показывает сервер analytics-mcp в списке MCP-серверов;
• сервер возвращает доступные аккаунты или отчёт по свойству, к которому у учётных данных есть права.

Если сервер отображается, но свойства отсутствуют, сначала проверьте права пользователя или сервисного аккаунта в GA4. Если сервер не появился в клиенте, проверьте путь к ADC, идентификатор Google Cloud project и возможность запуска pipx run analytics-mcp.

Команды и конфигурация выше сверены с официальным README, но их фактический запуск в рамках подготовки этого материала не выполнялся.

Полезные сценарии

Быстрая проверка контента

Задача: определить, какие страницы получили больше всего просмотров за выбранный период.

Что передать агенту: свойство GA4, диапазон дат, нужный показатель и ограничение по числу строк.

Пример запроса: «Покажи десять страниц с наибольшим числом просмотров за последние семь дней и сравни с предыдущими семью днями».

Результат: таблица страниц и показателей, которую можно сверить с отчётом GA4. Причину роста следует формулировать как гипотезу, пока она не подтверждена источниками трафика, UTM-метками или данными кампании.

Мониторинг событий после релиза

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

Что передать агенту: список ожидаемых событий, время релиза и нужное свойство.

Пример запроса: «Покажи количество событий sign_up и purchase за последние 30 минут».

Результат: отчёт в реальном времени с поступившими событиями. Пустой ответ сам по себе не доказывает поломку: причиной могут быть отсутствие активности, фильтры, задержка обработки или неверное свойство.

Анализ воронки

Задача: оценить прохождение заданной последовательности событий.

Что передать агенту: шаги воронки и период анализа.

Результат: отчёт по воронке с переходами между шагами. Этот сценарий использует ранний метод Data API и требует дополнительной проверки при обновлении сервера.

Квоты и ограничения Data API

По состоянию на 8 сентября 2026 года Data API разделяет запросы на три категории квот: Core, Realtime и Funnel. Каждый запрос расходует квоту только своей категории.[4]

Для стандартного свойства в каждой категории установлены следующие пределы:

• 200 000 токенов на свойство в день;
• 40 000 токенов на свойство в час;
• 14 000 токенов на сочетание проекта и свойства в час;
• 10 одновременно выполняемых запросов на свойство;
• 10 серверных ошибок с кодами 500 или 503 на сочетание проекта и свойства в час.

Для Analytics 360 соответствующие пределы выше: 2 000 000, 400 000, 140 000, 50 и 50. Отдельно для свойства действует лимит 120 потенциально пороговых запросов в час. К таким измерениям относятся userAgeBracket, userGender, brandingInterest, audienceId и audienceName.[4]

Стоимость запроса в токенах зависит от числа строк, количества показателей и измерений, сложности фильтров, длины периода, кардинальности данных и объёма событий. Большинство запросов расходует не более десяти токенов, но сложные отчёты могут потребовать больше.

Для наблюдения за расходом квоты добавьте в запрос Data API параметр:

{
  "returnPropertyQuota": true
}

Ответ будет содержать объект PropertyQuota с расходом текущего запроса и остатками квот.

Как отделять данные от интерпретации

Удобный формат ответа агента состоит из трёх частей:

• факт: показатель, период, фильтры и свойство GA4;
• интерпретация: возможное объяснение результата;
• проверка: следующий отчёт или внешний источник, который подтвердит объяснение.

Например, рост просмотров после рассылки ещё не доказывает причинную связь. Для проверки понадобятся источники трафика, параметры кампании и сравнимый период.

Учитывайте также настройки Reporting Identity, правила атрибуции, пороговые ограничения и различия между обычными и отчётами в реальном времени. Формулируйте запросы с точным диапазоном дат, показателями, измерениями и фильтрами.

Когда сервер не подходит

• Требуется менять события, связи, доступы или другие настройки GA4: MCP-сервер поддерживает только чтение.
• Нужны данные legacy Universal Analytics: Data API не совместим со свойствами Universal Analytics.
• Нужен гарантированно стабильный интерфейс для критичного процесса: проект пока имеет статус Experimental.
• Нужны отчёты без передачи внутренних данных языковой модели или MCP-клиенту.
• Требуется длительная массовая выгрузка данных: следует заранее оценить квоты и другие способы экспорта.
• Нужна автоматическая причинная интерпретация показателей: сервер возвращает данные, а вывод агента требует отдельной проверки.

Официальные ссылки

• Try the Google Analytics MCP server
• Репозиторий Google Analytics MCP Server
• Релизы проекта
• Обзор Google Analytics Data API
• Лимиты и квоты Data API
• Официальное видео по настройке

Следующий шаг

Чтобы связать отчёты GA4 с контентным и агентным контуром сайта, следующим чтением может стать Как сайт становится живым контуром: человек, агент, Notion и live-сайт.

Связанные материалы

• Блог: Почему личный сайт — это не визитка, а основа всей публичной системы
• База знаний: Cloudflare Agents SDK — stateful AI-агенты на Durable Objects

Подключение аналитики к агентному контуру требует отдельно продумать права, хранение учётных данных, журналирование запросов и правила проверки выводов.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov