search-console-mcp

MCP-сервер для Google Search Console, который предоставляет официальный Search Console API как инструменты для AI-агентов.

Его основная задача — производительность поиска и здоровье индекса: запросы кликов, показов, CTR и позиций по запросу, странице, стране, устройству или дате, проверка, проиндексирован ли URL и почему нет, а также управление sitemap-файлами и ресурсами аккаунта.

Чего он намеренно не делает: не запрашивает индексацию или переиндексацию URL — отдельный Indexing API поддерживает только страницы вакансий и прямых трансляций; не проверяет владение ресурсом (владелец должен добавить сервисный аккаунт в каждый ресурс) и не предоставляет данные Google Analytics — это отдельный Analytics Data API.

Удаление — по явному согласию. delete_sitemap и delete_site регистрируются только при установке GOOGLE_SEARCH_CONSOLE_ALLOW_DESTRUCTIVE — см. Конфигурацию.

Установка

claude mcp add search-console \
  -e GOOGLE_SERVICE_ACCOUNT_KEY_PATH=/path/to/service-account.json \
  -e GOOGLE_SEARCH_CONSOLE_SITE_URL=https://example.com/ \
  -- npx -y @orellbuehler/search-console-mcp

Флаги -e должны идти до разделителя --; всё, что указано после --, передаётся процессу сервера, а не читается как конфигурация.

Получение ключа сервисного аккаунта

1. В Google Cloud console выберите или создайте проект и включите Google Search Console API.

2. Перейдите в IAM & Admin → Service accounts → Create a service account. Необязательные шаги «grant access» можно пропустить — права Search Console выдаются отдельно, а не через роли Cloud IAM.

3. Откройте созданный сервисный аккаунт, перейдите на вкладку Keys и выберите Add key → Create new key → JSON. Файл скачивается один раз, после чего его нельзя получить повторно.

4. В Search Console откройте ресурс, перейдите в Settings → Users and permissions → Add user и вставьте адрес электронной почты сервисного аккаунта (name@project-id.iam.gserviceaccount.com). Предоставьте:

   • Restricted или Full для инструментов чтения (аналитика, sitemaps, проверка URL)

   • Full для submit_sitemap и delete_sitemap

5. Повторите шаг 4 для каждого ресурса, который должен видеть сервер — сервисный аккаунт не может самостоятельно подтверждать ресурсы.

6. Укажите GOOGLE_SERVICE_ACCOUNT_KEY_PATH — путь к скачанному JSON-файлу.

Относитесь к JSON-ключу как к паролю: он несёт все предоставленные вами права, и перед ним нет второго фактора защиты. Храните его вне репозитория и рассмотрите вариант с chmod 600.

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

Ресурс определяется либо как ресурс с префиксом URL, например https://example.com/ — имеют значение протокол и завершающий слэш, и https://example.com/, и http://example.com/ — это разные ресурсы, — либо как доменный ресурс вида sc-domain:example.com, который охватывает все поддомены и протоколы. Используйте ту либо иную форму в зависимости от того, как ресурс был добавлен в Search Console; list_sites покажет точные строки.

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

{
  "mcpServers": {
    "search-console": {
      "command": "npx",
      "args": ["-y", "@orellbuehler/search-console-mcp"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY_PATH": "/path/to/service-account.json",
        "GOOGLE_SEARCH_CONSOLE_SITE_URL": "https://example.com/"
      }
    }
  }
}

Примеры запросов

• «Какие у меня самые популярные поисковые запросы за этот месяц?»

• «Какие страницы получают больше всего кликов из Google и как это изменилось по сравнению с предыдущими 28 днями?»

• «Покажи запросы, содержащие 'pricing', где мы указываемся ниже 10-й позиции — это быстрые победы.»

• «Какая доля нашего трафика приходится на мобильные устройства, а какая — на десктоп?»

• «Построй график наших ежедневных кликов и показов за последние три месяца».

• «Из каких стран мы получаем показы, но почти не получаем кликов?»

• «Проиндексирован ли https://example.com/blog/launch? Если нет, почему?»

• «Перечисли наши sitemap и скажи, есть ли в них ошибки или предупреждения.»

• «Повторно отправь sitemap после вчерашней реструктуризации сайта.»

• «Какие конкурирующие страницы ранжируются по запросу 'mcp server'?»

• «Сравни трафик Discover с веб-поиском за этот квартал.»

Инструменты

Поисковая аналитика

Карты сайта

Ресурсы

Проверка URL

Примечания и предостережения

• Данные о производительности отстают примерно на ~2–3 дня. Инструменты быстрого запуска по усыновлению считают диапазон начинается 3 дня; data_state: "all" включает нов¨, но возможно, неполные данные.

• Данные хранятся 16 месяцев. Запросы, которые содержимое старее, не возвращают строк.

• Фильтрация конфиденциальных данных. Строки для редких запроcов скрываются, поэтому сумма по отдельным строкам запроса занимает меньше чем, SUM; делайте запрос без измерений для точной суммы.

• 25 000 строк на вызов. Используйте start_row для постраничной загрузки; если в ответе меньше строк, чем row_limit, — это последняя страница.

• Годовой лимит проверки URL составляет около 2 000 обращений/день на ресурс и 600/минуту — проверяйте выборочно, а не массово.

• Измерение hour требует data_state: "hourly_all" и охватывает только последние ~10 дней.

• Ваши данные переходят к LLM. Все, что возвращает инструмент, становится контекстом модели; не подключайте ресурсы, чьи данные не должны покидать вашу среду.

Разработка

npm install
npm run build         # tsc -p tsconfig.build.json -> dist/
npm test              # vitest run
npm run lint          # eslint src
npm run typecheck     # tsc --noEmit
npm run format        # prettier --write .

Проверьте собранный сервер на реальном ресурсе:

GOOGLE_SERVICE_ACCOUNT_KEY_PATH=/path/to/service-account.json \
GOOGLE_SEARCH_CONSOLE_SITE_URL=https://example.com/ \
npx @modelcontextprotocol/inspector node dist/index.js

CI / Публикация

CI запускает format:check, lint, typecheck, test и build на Node 20 и 22. Публикация происходит при создании релиза на GitHub через доверенную публикацию npm (OIDC, без токенов):

npm version patch
git push --follow-tags
gh release create "v$(node -p "require('./package.json').version")" --generate-notes

Лицензия

MIT © Orell Bühlera