ga-gsc-analytics

MCP-сервер только для чтения, предоставляющий данные Google Analytics 4 и Google Search Console (области analytics.readonly + webmasters.readonly) для Claude Code / Codex.

Впервые здесь? Следуйте ONBOARDING.md для пошагового руководства с нуля до рабочего состояния (установка Claude Code, получение учетных данных, авторизация, проверка). Остальная часть этого файла — справочный материал.

ИИ-агенты: этот файл также выполняет роль AGENTS.md — начните здесь для настройки, затем прочитайте skills/analyze-ga-gsc/SKILL.md о том, как использовать инструменты (проверки доступа, диапазоны дат по умолчанию, семантика GA4 и GSC, формат передачи для презентаций). Никогда не просите пользователя вставлять учетные данные в чат.

Инструменты

• analytics_auth_start / analytics_auth_status — локальный OAuth-поток + проверка статуса

• analytics_list_sources — список свойств GA4 и сайтов GSC, доступных авторизованной учетной записи

• ga_run_report — запуск отчета GA4

• gsc_query_search_analytics — запрос данных Search Console

• analytics_presentation_snapshot — объединенный снимок GA4 + GSC для отчетности

Related MCP server: BigQuery MCP Server

Настройка (для каждого пользователя)

Каждый пользователь авторизуется со своей учетной записью Google и хранит собственный локальный токен — никогда не передавайте секреты client_secret.json или tokens.json между машинами.

1. OAuth-клиент Google Cloud: создайте (или используйте существующий) OAuth 2.0 Desktop клиент в Google Cloud Console и скачайте его client_secret.json. Если экран согласия находится в статусе публикации "Testing", сначала добавьте учетную запись Google каждого нового пользователя как тестового пользователя, иначе авторизация завершится ошибкой access-denied.

2. Разместите учетные данные по пути ~/.config/ga-gsc-analytics/client_secret.json (или укажите GA_GSC_CLIENT_SECRET на свой путь).

3. Предоставьте доступ к данным: авторизующая учетная запись Google должна иметь реальные разрешения на целевое свойство GA4 (Analytics Admin → Property Access Management) и сайт GSC (Search Console → Settings → Users and permissions).

4. Соберите сервер (нужно только если вы изменяете mcp/server.mjs; в репозитории уже есть предварительно собранный mcp/server.bundle.cjs):

   pnpm install
   pnpm run build   # bundles mcp/server.mjs -> mcp/server.bundle.cjs

5. Зарегистрируйте MCP-сервер. Либо:

   • Claude Code, на уровне пользователя: claude mcp add ga-gsc-analytics -- node /path/to/ga-gsc-analytics/mcp/server.bundle.cjs

   • Claude Code / Codex, в рамках проекта: этот репозиторий уже содержит относительный .mcp.json ({"mcpServers": {"ga_gsc_analytics": {"command": "node", "args": ["./mcp/server.bundle.cjs"]}}}) — скопируйте его в проект или сделайте симлинк/включите всю эту папку, и он будет автоматически подхвачен при открытии проекта.

6. Авторизуйтесь: вызовите инструмент analytics_auth_start из вашего ИИ-инструмента — он открывает локальный браузерный OAuth-поток и записывает ~/.config/ga-gsc-analytics/tokens.json.

7. Проверьте: вызовите analytics_auth_status (должен показать authorized: true), затем analytics_list_sources, чтобы убедиться, что ожидаемые свойства GA4 / сайты GSC отображаются.

Переопределения конфигурации

Разработка

pnpm run check   # syntax check
pnpm test        # node --test tests/*.test.mjs