mcp-google-gsc

MCP-сервер для Google Search Console -- поисковая аналитика, проверка URL и управление сайтами через Claude.

Возможности

• Search Analytics -- Запросы кликов, показов, CTR и позиций с гибкими фильтрами по измерениям (query, page, device, country, date)

• URL Inspection -- Проверка статуса индексации, мобильной удобности и расширенных результатов для любого URL

• Site Listing -- Список всех подтверждённых свойств Search Console, доступных вашей аутентифицированной учётной записи (пользователь OAuth или сервисный аккаунт)

• Multi-Client Support -- Управление несколькими свойствами GSC с сопоставлением конфигурации по каталогам

Related MCP server: Google Search Console MCP Server

Установка

Из npm

npm install mcp-google-gsc

Из исходного кода

git clone https://github.com/mharnett/mcp-search-console.git
cd mcp-google-gsc
npm install
npm run build

Конфигурация

Безопасность: Никогда не делитесь файлом .mcp.json и не коммитьте его в git -- он может содержать учётные данные API. Добавьте .mcp.json в ваш .gitignore.

mcp-gsc поддерживает два режима аутентификации. Выберите тот, который подходит для вашей настройки. Ни один из них не требует файла, находящегося по жёстко заданному локальному пути -- учётные данные берутся из переменных окружения (или из создаваемого вами config.json).

Какой режим использовать:

• Сервисный аккаунт (Режим B) -- рекомендуется для автоматического / серверного / безголового использования. У сервисного аккаунта нет интерактивного входа, который мог бы истечь или потребовать повторного согласия, поэтому он подходит для постоянно работающих развёртываний. Единственное требование настройки -- адрес электронной почты сервисного аккаунта должен быть предоставлен доступ к каждому свойству Search Console, которое вы хотите запрашивать (см. Режим B).

• Пользовательский OAuth (Режим A) -- для личного / интерактивного использования, когда вы хотите авторизоваться через свой собственный аккаунт Google.

Приоритет при настройке обоих: если файл ключа сервисного аккаунта явно задан (GOOGLE_APPLICATION_CREDENTIALS или credentials_file в config.json), он имеет приоритет над любым OAuth refresh-токеном или сохранёнными учётными данными OAuth. Если не настроено ни одного, сервер громко завершает работу при запуске с сообщением о начале работы, а не молча угадывает -- нет локального значения по умолчанию и нет молчаливого переключения между режимами во время выполнения.

Режим A: Пользовательский OAuth (используйте свой аккаунт Google)

Используйте это, если хотите авторизоваться через свой собственный аккаунт Google (аккаунт, у которого есть доступ к Search Console). Лучше всего для личного / интерактивного использования.

1. В Google Cloud Console создайте OAuth 2.0 Client ID типа Desktop app и включите Search Console API. (Для клиента типа Desktop app Google принимает любой loopback-редирект http://localhost -- вам не нужно предварительно регистрировать порт.)

2. Экспортируйте учётные данные клиента:

   export GOOGLE_GSC_CLIENT_ID=...apps.googleusercontent.com
   export GOOGLE_GSC_CLIENT_SECRET=...

3. Создайте refresh-токен (откроется браузер, используется PKCE + access_type=offline):

   node get-refresh-token.cjs

   Не перенаправляйте stdout этой команды в общий журнал -- она намеренно выводит refresh-токен в stdout.

4. Скопируйте выведенную строку в ваше окружение:

   export GOOGLE_GSC_REFRESH_TOKEN=...

Сервер считывает GOOGLE_GSC_CLIENT_ID, GOOGLE_GSC_CLIENT_SECRET и GOOGLE_GSC_REFRESH_TOKEN из окружения во время выполнения.

В качестве альтернативы запустите интерактивный помощник npx mcp-gsc-auth, который выполняет тот же поток PKCE OAuth, позволяет выбрать свойство Search Console по умолчанию и записывает результат в файл учётных данных для конкретного пользователя.

Режим B: Сервисный аккаунт (рекомендуется для автоматического / серверного использования)

Используйте это для серверных / безголовых / постоянно работающих сред -- это рекомендуемый путь, когда рядом нет человека, который мог бы завершить или обновить интерактивный вход.

1. Создайте сервисный аккаунт Google Cloud с доступом к Search Console API и скачайте его JSON-файл ключа.

2. Предоставьте адресу электронной почты сервисного аккаунта доступ к каждому свойству Search Console, которое вы хотите запрашивать (добавьте его как пользователя в Search Console). Без этого предоставления доступа к свойству сервисный аккаунт сможет аутентифицироваться, но не увидит ни одного сайта.

3. Укажите серверу путь к файлу ключа через переменную окружения (без жёстко заданного пути):

   export GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/service-account-key.json

Область OAuth

Оба режима запрашивают одну только для чтения область: https://www.googleapis.com/auth/webmasters.readonly. Все четыре инструмента выполняют чтение -- ничего не записывают -- поэтому сервер никогда не запрашивает доступ на чтение/запись.

Область определяется один раз в config.json в разделе oauth.scope (см. config.example.json). Помощник OAuth и среда выполнения считывают одно и то же значение, поэтому они никогда не расходятся. Если config.json отсутствует (например, при новой установке), используется сохранённое значение по умолчанию только для чтения.

Мультиклиентская конфигурация (необязательно)

Чтобы сопоставить рабочие каталоги со свойствами Search Console, создайте config.json в корне проекта (см. config.example.json):

{
  "oauth": {
    "scope": "https://www.googleapis.com/auth/webmasters.readonly"
  },
  "clients": {
    "my-project": {
      "name": "My Project",
      "folder": "/path/to/project",
      "site_url": "https://example.com/"
    }
  }
}

Использование

Добавьте в ваш .mcp.json для Claude Code:

{
  "mcpServers": {
    "gsc": {
      "command": "node",
      "args": ["/path/to/mcp-gsc/dist/index.js"]
    }
  }
}

Или если установлено глобально:

{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["mcp-google-gsc"]
    }
  }
}

Claude Desktop: Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows).

Инструменты

gsc_search_analytics

Поддерживает измерения: query, page, device, country, date. Фильтруйте по любому измерению с операторами, такими как equals, contains, notContains. Диапазон дат по умолчанию -- последние 28 дней.

gsc_inspection

Возвращает покрытие индексации, статус сканирования, вердикт о мобильной удобности и детали расширенных результатов для конкретного URL в свойстве.

Архитектура

• Устойчивость -- Использует cockatiel для повторных попыток с экспоненциальной задержкой и шаблонов автоматического выключателя для всех вызовов Google API

• Логирование -- Структурированное логирование через pino с настраиваемыми уровнями логирования

• Обработка ответов -- Ответы обрезаются до 200 КБ, чтобы оставаться в пределах лимитов транспорта MCP

Лицензия

MIT -- см. LICENSE.

Создано Марком Харнеттом / drak-marketing