Google Search Console MCP

MCP-сервер для Google Search Console API — данные о производительности поиска, статус индексации URL, управление sitemap и список свойств.

Работает тремя способами из одной кодовой базы: stdio (локально, через npx), Streamable HTTP (самостоятельный хостинг) и Cloudflare Workers (размещённый по URL). Реализует MCP 2026-07-28 с автоматическим откатом на 2025-11-25, 2025-06-18 и 2025-03-26, поэтому работает с клиентами по обе стороны изменения протокола.

Ноль зависимостей во время выполнения.

Быстрый старт

npx google-search-console-mcp auth

Это проведёт вас через создание Google OAuth-клиента, запустит процесс согласия, проверит учётные данные на живом API и выведет готовый к вставке блок конфигурации для вашего MCP-клиента. Три минуты, в основном ожидание интерфейса Google Cloud.

Затем вставьте выведенный JSON в конфигурацию клиента и перезапустите его.

Related MCP server: searchconsole-mcp

Инструменты

Каждый метод API Search Console v1, плюс два составных.

Проверка сайта и sites.add/sites.delete намеренно не предоставляются — добавление и проверка свойств — это браузерный процесс, который не подходит для инструмента агента.

Сервер также предоставляет промпты (performance_review, indexing_audit, query_opportunities, sitemap_health) и ресурсы (gsc://guide/search-analytics, gsc://guide/url-inspection, gsc://guide/sitemaps), которые агенты могут читать по требованию.

Аутентификация

Шаг 1 — создайте Google OAuth-клиент

Это делается только один раз. Сервер не может сделать это за вас: Google требует человека в своей консоли.

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

2. Включите Search Console API для этого проекта.

3. Настройте экран согласия OAuth. Внешний подходит для личного использования. Добавьте свой аккаунт Google в раздел Тестовые пользователи.

4. Перейдите в Учётные данные → Создать учётные данные → Идентификатор клиента OAuth. Выберите тип приложения Desktop app.

5. Скопируйте Идентификатор клиента и Секрет клиента.

Тестирование против публикации. Пока экран согласия находится в режиме Тестирование, Google истекает срок действия refresh-токенов через 7 дней, и вам придётся повторно запускать auth еженедельно. Публикация приложения (экран согласия → Опубликовать приложение) делает их долговечными. Для однопользовательского внутреннего инструмента публикация безопасна и не требует проверки Google, если вы остаётесь в рамках областей webmasters.

Шаг 2 — запустите процесс настройки

npx google-search-console-mcp auth

Это открывает небольшую страницу настройки, обслуживаемую с 127.0.0.1. Вставьте идентификатор клиента и секрет, выберите полный или только чтение, и он запустит процесс согласия, обменяет код (с PKCE) на refresh-токен и вызовет list_sites, чтобы доказать, что учётные данные работают — показывая вам точные свойства, к которым они могут получить доступ.

Финальная страница даёт вам блоб учётных данных и готовый к вставке конфиг для Claude Desktop, Claude Code и удалённых развёртываний, каждый с кнопкой копирования. Те же значения выводятся в терминал как запасной вариант.

На машине без головы или через SSH используйте auth --terminal для версии с подсказками.

Вы получаете блоб учётных данных — JSON в base64url-кодировке, содержащий ваш идентификатор клиента, секрет клиента и refresh-токен:

eyJ2IjoxLCJjcmVkZW50aWFscyI6eyJ0eXBlIjoib2F1dGhfcmVmcmVzaF90b2tlbiIsImNsaWVu…

Относитесь к блобу как к паролю. Любой, кто им владеет, имеет доступ к вашей Search Console, пока вы не отзовёте его на myaccount.google.com/permissions.

Он существует как единая непрозрачная строка, чтобы одно значение содержало всё, что нужно серверу — оно помещается прямо в переменную окружения или заголовок Authorization без файла учётных данных на диске.

Альтернативы OAuth-процессу

Сервисный аккаунт. Полезен для CI и для свойств, принадлежащих команде. Создайте его в Google Cloud, затем добавьте его client_email как пользователя свойства в Search Console (Настройки → Пользователи и разрешения). Закодируйте загруженный файл ключа напрямую:

base64 -i service-account.json | tr -d '\n'

Сервер принимает сырой ключ сервисного аккаунта как блоб — обёртка не нужна.

Существующий токен доступа. Установите {"type":"access_token","access_token":"ya29..."}. Обновление невозможно, поэтому это подходит только для короткоживущих скриптов.

Области

Выбор режима только для чтения во время auth запрашивает более узкую область. --read-only на сервере — это отдельный блок подстраховки, который отклоняет изменяющие инструменты до обращения к API.

Запуск

Локально (stdio)

Конфиг, выведенный auth:

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "google-search-console-mcp"],
      "env": { "GSC_CREDENTIALS": "<your blob>" }
    }
  }
}

Расположение файлов конфигурации:

Установите его правильно, если не хотите каждый раз использовать npx:

npm install -g google-search-console-mcp

Самостоятельный HTTP

GSC_CREDENTIALS=<blob> npx google-search-console-mcp http --port 8787

Обслуживает POST http://127.0.0.1:8787/mcp. По умолчанию привязывается к loopback — передайте --host 0.0.0.0 осознанно, если хотите его открыть, и поставьте TLS перед ним, если сделаете это.

Браузерным клиентам отказывается, если вы их не укажете, потому что сервер, хранящий собственные учётные данные, иначе мог бы управляться любой страницей, которую вы посещаете. Обычные MCP-клиенты не отправляют Origin и не затрагиваются; браузерному нужно указать его происхождение:

npx google-search-console-mcp http --allowed-origins http://localhost:6274   # MCP Inspector

Отклонённое происхождение получает 403, который браузер не может прочитать (на отказ нет CORS-заголовков, намеренно), поэтому это проявляется как общая ошибка CORS — проверьте строку Origins: при запуске сервера, если браузерный клиент не может подключиться. --allowed-origins '*' отключает проверку.

Cloudflare Workers

git clone https://github.com/russjeffery/google-search-console-mcp.git
cd google-search-console-mcp
npm install
npx wrangler deploy

Ваш endpoint: https://google-search-console-mcp.<subdomain>.workers.dev/mcp.

По умолчанию Worker не хранит секреты. Каждый клиент отправляет свой собственный блоб учётных данных как bearer-токен, поэтому общее развёртывание никогда не хранит чьи-либо учётные данные Google, и разные пользователи одного URL видят только свои свойства.

Для частного однопользовательского развёртывания вместо этого:

npx wrangler secret put GSC_CREDENTIALS     # your blob
npx wrangler secret put MCP_SHARED_SECRET   # token clients must present

Клиенты затем отправляют общий секрет, а не блоб.

Необязательные vars в wrangler.jsonc:

Подключение клиента к удалённому серверу

{
  "mcpServers": {
    "google-search-console": {
      "type": "http",
      "url": "https://your-worker.workers.dev/mcp",
      "headers": { "Authorization": "Bearer <your blob>" }
    }
  }
}

В веб-интерфейсе или настольном приложении Claude добавьте его в Настройки → Коннекторы → Добавить пользовательский коннектор.

Выведите это заполненным для вашего собственного развёртывания:

npx google-search-console-mcp config --url https://your-worker.workers.dev/mcp

CLI

google-search-console-mcp [command] [options]

  stdio     Run as a stdio MCP server (default)
  http      Run a local Streamable HTTP MCP server
  auth      Guided setup in your browser: OAuth flow, blob, client config
  config    Print client config for existing credentials
  doctor    Verify credentials by calling the API

doctor — первое, к чему стоит обратиться, когда что-то не работает — он разделяет «учётные данные неверны» и «клиент не может запустить сервер».

Опции: --credentials <blob>, --site <siteUrl>, --read-only, --port, --host, --endpoint, --secret, --allowed-origins, --url, --terminal, --no-browser.

--allowed-origins принимает список через запятую; не задано означает только не-браузерные клиенты. Записи сопоставляются без учёта регистра, завершающий слэш игнорируется.

--site задаёт свойство по умолчанию, чтобы инструменты могли опускать siteUrl — удобно, когда развёртывание охватывает только один сайт.

Поддержка протокола

Редакция 2026-07-28 существенно изменила Streamable HTTP: нет рукопожатия initialize, нет сессий, нет Mcp-Session-Id, нет GET-потока, а метаданные на запрос в params._meta зеркалируются в HTTP-заголовки. Официальный TypeScript SDK ещё не реализует это, поэтому уровень протокола здесь написан вручную и поддерживает обе эпохи.

Эпоха определяется на каждый запрос: запрос с современным _meta обслуживается как современный, initialize выбирает устаревший. GET и DELETE на endpoint возвращают 405, как предписывает редакция.

Проверка заголовков строгая по умолчанию, согласно спецификации. Если клиент отправляет современный _meta без зеркалирования заголовков, установите MCP_STRICT_HEADERS=0 (или --loose-headers) вместо понижения версии.

Об авторизации: в спецификации OAuth 2.1 предполагается, что сервер является ресурсным сервером с собственным сервером авторизации. Этот сервер вместо этого использует bearer-токен для прямой передачи ваших учётных данных Google — спецификация допускает пользовательские стратегии, а значит, размещённое развёртывание не хранит секретов и не нуждается в базе пользователей. Оборотная сторона — клиентам, ожидающим автоматического обнаружения OAuth, потребуется настроить заголовок вручную, как показано выше.

Работа с данными

Четыре свойства данных Search Console приводят к большинству ошибочных выводов. Описания инструментов и встроенный навык разбирают их подробно; кратко:

1. Данные задерживаются на ~3 дня. Используйте lastDays, и инструменты выберут безопасное окно. Диапазон, заканчивающийся сегодня, покажет ложное снижение.

2. Данные по запросам фильтруются в целях конфиденциальности. Группировка по query молча отбрасывает редкие запросы, поэтому клики на уровне запросов никогда не суммируются в общий итог по свойству. Этот разрыв — не потерянный трафик.

3. Позиция инвертирована. Позиция 3 лучше позиции 8; отрицательное изменение — это улучшение. compare_search_analytics возвращает явный флаг improved.

4. Средние значения компенсируют друг друга. Ровные итоговые цифры часто скрывают крупные противоположные изменения. Группируйте по странице или запросу, прежде чем делать вывод, что ничего не изменилось.

Квоты

• Аналитика поиска: ~1 200 запросов в минуту на свойство.

• Инспекция URL: ~2 000 в день на свойство — сдерживающее ограничение. Дискретизируйте осознанно.

Недоступно через API

Сводный отчёт Index Coverage, живое тестирование URL, запрос индексации, Core Web Vitals, действия вручную, проблемы безопасности, отчёты по ссылкам и удаления не имеют эквивалента в API, поэтому их здесь нет. Постраничный inspect_url — ближайшая замена для вопросов о покрытии.

Навык агента

skills/google-search-console/ — это готовый к установке навык, который обучает агента правильно использовать эти инструменты: рассмотренные выше ловушки, диагностическую лестницу для изменений трафика, эвристику поиска возможностей и справочные таблицы состояний покрытия.

cp -r skills/google-search-console ~/.claude/skills/

Тот же справочный материал доступен в Runtime через ресурсы сервера gsc://guide/*, так что агенты без установленного навыка всё равно могут его прочитать.

Разработка

npm install
npm run build       # compile to dist/
npm run typecheck
npm test
npm run cf:dev      # Worker locally via wrangler

Быстрая ручная проверка через HTTP-транспорт:

GSC_CREDENTIALS=<blob> npm run build && node dist/bin/cli.js http &

curl -s http://127.0.0.1:8787/mcp \
  -H 'content-type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}' | jq '.result.tools[].name'

Устранение неполадок

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

• Блок учётных данных — это ваш доступ к Google. Не отправляйте его в репозиторий, не вставляйте в общие документы. Отзовите доступ на myaccount.google.com/permissions.

• HTTP-режим по умолчанию привязан к 127.0.0.1 и проверяет Origin по значению ALLOWED_ORIGINS, чтобы блокировать DNS rebinding. Если значение не задано, ни один источник из браузера не разрешён — перечислите их явно или используйте *, чтобы отключить проверку. /health и / исключены из проверки; они не открывают функций, требующих учётных данных.

• Сравнение общего секрета выполняется с проверкой длины и за постоянное время.

• Развёртывание в среде Worker по умолчанию вообще не хранит учётные данные.

• --read-only / GSC_READ_ONLY=1 блокирует изменения карты сайта независимо от предоставленной области OAuth.

License

MIT