API ВЕГА

mcp-gsc

Часть набора открытых SEO-инструментов DigestSEO.

Для самостоятельного хостинга доступен лаунчер @digestseo/mcp-gsc:

npx -y @digestseo/mcp-gsc

Лаунчер npm запускает локальный Streamable HTTP Worker, доступный только через loopback-интерфейс на 127.0.0.1 (по умолчанию порт 8080); это не MCP-процесс, работающий через stdio. Команду npx можно выполнять из любого каталога: лаунчер находит конфигурацию Worker в установленном пакете. Клиенты, запускающие пакет, должны подключаться к http://127.0.0.1:8080/mcp. Для этого предварительно задайте переменные среды Google OAuth и шифрования токенов, описанные в SETUP.md. Если переменные GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET или TOKEN_ENCRYPTION_KEY отсутствуют или не содержат значения, лаунчер завершит работу до запуска Wrangler. Он также отклонит непустое значение TOKEN_ENCRYPTION_KEY, если оно не является корректным base64-кодированным значением, декодируемым ровно в 32 байта. В сообщениях об ошибках указывается только некорректная или отсутствующая настройка — её секретное значение не раскрывается, поэтому не будет запущена OAuth-сессия с неверной конфигурацией. Лаунчер передаёт секретные значения через среду дочернего процесса, а Wrangler загружает их как объявленные локальные секреты; значения не передаются в аргументах командной строки --var. Перед первой авторизацией через Google добавьте в Google Cloud точный адрес обратного вызова http://127.0.0.1:8080/google/callback (или укажите тот же пользовательский PORT, с которым запускаете сервер). При запуске лаунчер выводит оба URL.

Локальное состояние KV и Durable Object, включая зашифрованную сессию Google, по умолчанию хранится в ~/.mcp-gsc/state, а не в кэше npm с версиями пакетов. Благодаря этому локальное подключение сохраняется при обновлении пакета и обычной очистке кэша npm. Чтобы использовать другой каталог, задайте MCP_GSC_STATE_DIR. При повторном использовании существующего состояния указывайте тот же TOKEN_ENCRYPTION_KEY, поскольку сохранённые токены обновления зашифрованы с его помощью. При запуске лаунчер выводит фактический каталог состояния. Для первого выпуска со стабильным путём хранения может потребоваться повторно подключить Google: в предыдущих версиях лаунчера локальное состояние хранилось в кэше npm с пакетами.

По умолчанию локальный лаунчер использует GSC_ACCESS_MODE=readwrite. Для аналитики и отчётности с минимально необходимыми разрешениями задайте в среде GSC_ACCESS_MODE=readonly перед запуском npx. Лаунчер передаст это значение локальному Worker: OAuth запросит только разрешение Search Console на чтение, а шесть инструментов для изменения данных не будут зарегистрированы.

Инструкции по настройке Google OAuth и развёртыванию в Cloudflare приведены в SETUP.md.

Подключение локального лаунчера

Чтобы воспользоваться проверенным способом быстрого подключения, сначала запустите лаунчер npm, предварительно задав переменные среды Google OAuth и шифрования токенов, описанные в SETUP.md:

npx -y @digestseo/mcp-gsc

Затем подключите MCP-клиент к loopback-адресу лаунчера:

http://127.0.0.1:8080/mcp

Для самостоятельно развёрнутых Cloudflare Worker используется адрес https://.workers.dev/mcp. В репозитории сейчас не предлагается удалённый сервер, размещённый владельцем, как вариант быстрого подключения: его развёрнутая версия пока не соответствует контракту инструментов опубликованного пакета.

Claude Code

claude mcp add --transport http gsc http://127.0.0.1:8080/mcp

OpenAI Codex CLI / IDE

codex mcp add gsc --url http://127.0.0.1:8080/mcp

Codex CLI и расширение Codex IDE используют общую конфигурацию MCP. Поэтому достаточно один раз зарегистрировать сервер, чтобы подключение стало доступно в обоих клиентах. Перед использованием подключения запустите лаунчер npm. Когда потребуется аутентификация, Codex откроет OAuth-процесс сервера.

Cursor

Если установить этот репозиторий как плагин Cursor, Cursor также обнаружит три встроенных Agent Skills, которые объединяют инструменты MCP в рабочие сценарии с проверкой достоверности данных: gsc-weekly-review, gsc-indexing-triage и gsc-search-opportunities. Кнопка «Добавить в Cursor» выше устанавливает только подключение MCP; встроенные навыки входят в состав плагина Cursor из этого репозитория.

Кнопка и конфигурация MCP плагина выше предназначены для Cursor, запущенного на том же компьютере, что и лаунчер npm. Cursor Cloud Agents работают в изолированных облачных VM и не могут подключаться к 127.0.0.1 на вашем компьютере. Для Cloud Agents разверните собственный Worker с внешним доступом по HTTPS и добавьте его URL /mcp через элементы управления MCP на странице cursor.com/agents. Там Cursor поддерживает HTTP-серверы MCP и OAuth. Не используйте loopback-URL для Cloud Agent.

GitHub Copilot CLI

copilot plugin marketplace add AKzar1el/mcp-gsc
copilot plugin install mcp-gsc@digestseo

Подключение через marketplace позволяет находить плагин и обновлять его с помощью инструментов marketplace в Copilot. Также по-прежнему поддерживается прямая установка из репозитория: copilot plugin install AKzar1el/mcp-gsc. Плагин Copilot включает те же три Agent Skills и локальную конфигурацию MCP для loopback-подключения. Перед использованием MCP-сервера плагина запустите лаунчер npm: плагин не запускает и не развёртывает mcp-gsc самостоятельно.

Gemini CLI

gemini extensions install https://github.com/AKzar1el/mcp-gsc

Расширение Gemini CLI включает проверенную локальную конфигурацию MCP для loopback-подключения и те же три Agent Skills: gsc-weekly-review, gsc-indexing-triage и gsc-search-opportunities. Перед использованием расширения запустите лаунчер npm: расширение не запускает и не развёртывает mcp-gsc самостоятельно.

Kiro

Перед использованием любой кнопки установки или плагина Copilot запустите лаунчер npm. При первом использовании завершите авторизацию через Google OAuth.

ChatGPT — ChatGPT не может напрямую подключаться к этому loopback-адресу 127.0.0.1. Для приватного или локального использования создайте OpenAI Secure MCP Tunnel, а затем запустите tunnel-client на том же компьютере, что и лаунчер, чтобы он мог подключиться к http://127.0.0.1:8080/mcp. При создании приложения ChatGPT выберите подключение Tunnel и укажите этот туннель. Для настройки туннеля потребуются OpenAI tunnel_id и API-ключ для запуска. Подробнее см. в руководстве OpenAI по Secure MCP Tunnel. Туннель сохраняет приватность MCP-сервера и предназначен для частного подключения и режима разработчика, а не для публичного распространения плагинов.

Также можно развернуть собственный удалённый Cloudflare Worker и добавить его HTTPS-адрес /mcp как пользовательское приложение MCP в режиме Developer mode. См. раздел «Подключение в AI-клиенте» ниже.

Самостоятельно размещаемый сервер Model Context Protocol (MCP) для Google Search Console. Подключите его к Claude.ai, Cursor, ChatGPT или любому совместимому с MCP клиенту и задавайте AI-ассистенту вопросы об органическом поисковом трафике сайта — показах, кликах, популярных запросах, статусе индексации и состоянии Sitemap. Данные поступают напрямую из вашего аккаунта Google.

Сервер работает на Cloudflare Workers и поддерживает авторизацию через Google OAuth. Подключите сервер в клиенте, ознакомьтесь со страницей согласия mcp-gsc, где указаны клиент MCP, запрашивающий доступ, и необходимые разрешения, затем войдите в Google и предоставьте запрошенные разрешения Google Search Console. Не нужно копировать API-ключи или управлять JSON-файлами сервисных аккаунтов.

Инструменты

По умолчанию (GSC_ACCESS_MODE=readwrite) сервер предоставляет 23 инструмента. Инструменты только для чтения аналитики и отчётов отмечены подсказкой MCP readOnlyHint; перечисленные ниже инструменты записи могут изменять ресурсы Search Console, файлы Sitemap или состояние индексации. Установите GSC_ACCESS_MODE=readonly, чтобы запрашивать только область доступа Search Console для чтения и предоставлять 16 инструментов, которым не нужны права на запись или отдельная область доступа Indexing API.

ИнструментДоступНазначение
server.capabilitiesЧтениеПеречисляет все инструменты, доступные на сервере, и сообщает о состоянии локальных учётных данных Google. Значение connected означает, что сохранены учётные данные для обновления токена; в ответе также указываются auth_status_basis и provider_auth_live_verified: false, поскольку этот вызов для обнаружения возможностей не обращается к Google. При последующем вызове инструмента Google может потребоваться повторное подключение, если срок действия учётных данных истёк или они были отозваны. Аргументы не принимает.
sites.listЧтениеПеречисляет ресурсы Search Console, доступные подключённому аккаунту Google (siteUrl, permissionLevel).
sites.getЧтениеПолучает сведения об одном ресурсе Search Console с точным совпадением и уровне разрешений подключённого аккаунта.
analytics.queryЧтениеВозвращает показы, клики, CTR и среднюю позицию за выбранный период с разбивкой по параметрам, фильтрами, безопасной пагинацией и выбором типа поиска. Передайте dimensions: [], чтобы получить итоги по всему сайту; в агрегированной строке Google может не быть поля keys. Search Analytics не гарантирует возврат всех строк данных и может предоставлять только верхние строки, поэтому исчерпание локальной пагинации не доказывает, что получен полный набор данных поставщика. Значение data_state: "all" может включать свежие предварительные данные, а final возвращает только окончательные данные; в ответах отражаются data_state и preliminary_data_possible, а при группировке по дате и часу сохраняются метаданные Google о границах неполных данных, если они возвращены. Обнаружение параметров поискового представления выполняется в два этапа: сначала сгруппируйте данные только по searchAppearance, чтобы узнать точные значения, возвращаемые Google для ресурса, затем в отдельном запросе отфильтруйте результаты по одному из найденных значений при группировке по странице, запросу, стране, устройству, дате или часу. Для search_type: "discover" или "googleNews" значение position_supported равно false: в таких отчётах доступны клики, показы и CTR, но не средняя позиция, поэтому в возвращённых строках может отсутствовать position, а группировка и фильтрация по запросам недоступны. В текущей документированной версии Search Analytics API нет отдельного типа поиска или параметра фильтра для специализированных отчётов Search Console о производительности генеративного AI, поэтому значение generative_ai_report_isolatable равно false. Новый мультимодальный фильтр веб-поиска в интерфейсе Search Console также не представлен среди документированных параметров Search Analytics API, поэтому значение multimodal_report_isolatable равно false.
insights.page_queries / insights.query_pagesЧтениеПозволяют перейти от одной конкретной страницы к связанным с ней запросам Search Console или от одного конкретного запроса к страницам, показанным Google, с пагинацией через row_limit / start_row. Эти вспомогательные инструменты для анализа запросов поддерживают веб-поиск, поиск по изображениям и видео, а также вкладку «Новости» в результатах поиска. Discover и отчёт Google News не поддерживаются, поскольку в них нет данных по запросам.
urls.inspectЧтениеВозвращает отчёт Google URL Inspection для версии одной страницы, которая сейчас известна Google и находится в его индексе. Это не проверка URL в реальном времени; данные о пригодности для мобильных устройств устарели.
urls.inspect_manyЧтениеПроверяет проиндексированные Google версии не более чем 10 URL за один вызов, ограничивая параллельную обработку тремя запросами и сохраняя порядок результатов согласно порядку входных данных. Для каждого URL по-прежнему расходуется один запрос Google URL Inspection и одна единица общего лимита сервера на проверки. Проверка URL в реальном времени не выполняется.
sitemaps.list / sitemaps.getЧтениеПеречисляют отправленные файлы Sitemap или возвращают подробные сведения об одном из них. lastSubmitted указывает время отправки Sitemap в Search Console, а lastDownloaded — время последней загрузки файла Google. Ни одно из этих значений не отражает время изменения или развёртывания файла Sitemap, а также время сканирования или индексации страницы.
insights.quick_wins / insights.cannibalization / insights.content_decayЧтениеВыявляют возможности на основе средней позиции, пересечения запросов и страниц, а также подтверждённого данными снижения числа кликов. Кандидаты для быстрого улучшения — это обнаруженные сочетания запросов и страниц, отобранные по средней позиции в агрегированных данных Search Console; они не подтверждают стабильность текущей позиции, а CTR учитывается как контекст, но не как критерий отбора. Итоговые значения и доли для кандидатов на каннибализацию относятся к обнаруженным сочетаниям запросов и страниц, а не к фактическим итогам по запросу на уровне ресурса. Результаты анализа снижения эффективности контента сравнивают только страницы, возвращённые для обоих периодов, и не считают отсутствие строки в одном из периодов нулевым трафиком.
indexing.list_pages / analytics.compareЧтениеАнализируют страницы, получающие показы в Search Console, и сравнивают два периода. При необходимости для обоих периодов можно задать одинаковый тип поиска и фильтры по запросу, странице, стране, устройству и поисковому представлению. analytics.compare сравнивает только ключи измерений, возвращённые в ответах Search Analytics для обоих периодов; отсутствие ключа в одном из неполных ответов Search Analytics не считается нулевым значением показателей. Поскольку сравнение включает среднюю позицию, Discover и Google News не поддерживаются. indexing.list_pages возвращает данные об эффективности, а не об охвате индекса: URL, которого нет в списке, всё ещё может быть проиндексирован. Чтобы узнать статус индексации конкретного URL, используйте urls.inspect / urls.inspect_many.
reports.weekly_digestЧтениеСоздаёт понятный текстовый отчёт об эффективности за семь дней: показывает изменения показателей, лучшие страницы и рекомендует одно действие. Изменения запросов сравниваются только по строкам, возвращённым в обоих недельных наборах Search Analytics. Если запрос отсутствует в одном из ответов с ограниченным числом строк, это не считается нулевым значением, поскольку Google не гарантирует возврат всех строк данных.
sites.add / sites.deleteЗаписьДобавляют ресурс в набор сайтов Search Console подключённого аккаунта или удаляют его оттуда. sites.add возвращает ownership_verification_performed: false, поскольку подтверждение права собственности выполняется отдельно через Google Site Verification или Search Console. sites.delete удаляет ресурс из набора сайтов Search Console этого аккаунта, но не сам сайт.
sitemaps.submit / sitemaps.deleteЗаписьОтправляют или удаляют файл Sitemap.
indexing.statusЧтениеВозвращает последние успешно полученные Google подтверждения уведомлений Indexing API URL_UPDATED / URL_DELETED для ранее отправленного URL. Это только метаданные уведомлений, а не данные об охвате индекса, статусе сканирования, завершении индексации или удаления. Для работы требуется GSC_ACCESS_MODE=readwrite, поскольку конечная точка Google для получения метаданных использует область доступа Indexing API OAuth.
indexing.requestЗаписьОтправляет запрос на индексацию через Indexing API Google. Сейчас Google ограничивает использование этого API страницами с разметкой JobPosting или страницами трансляций в реальном времени, где внутри VideoObject указано BroadcastEvent. API недоступен для отправки обычных веб-страниц. Стандартный лимит Google в 200 запросов на публикацию в день для проекта предназначен для начальной настройки и тестирования, а не для постоянного использования; для выделения ресурсов и дальнейшего использования требуется дополнительное одобрение. Отправленные запросы проходят проверку на спам.
indexing.removeЗаписьОтправляет уведомление URL_DELETED для ранее допущенной к Indexing API страницы. Перед отправкой запроса URL должен возвращать HTTP 404/410 или содержать директиву noindex в метаданных robots. Подтверждение Google не доказывает, что удаление завершено; для проверки состояния индекса используйте URL Inspection.

Календарные даты Search Analytics (start_date, end_date и даты периодов сравнения) рассчитываются по календарю Google для тихоокеанского времени (America/Los_Angeles, UTC-8/UTC-7 в зависимости от перехода на летнее время), а не по местному времени вызывающей стороны или UTC. Это правило также применяется к диапазонам дат Search Analytics, которые сервер формирует автоматически или использует по умолчанию.

Ресурсы платформ. Теперь Search Console поддерживает в интерфейсе ресурсы аккаунтов социальных сетей и видеоплатформ, таких как Instagram, TikTok, X и YouTube. Однако в текущей документации Google по Search Console API для siteUrl определены только форматы ресурсов с префиксом URL и веб-ресурсов sc-domain:; формат идентификаторов ресурсов платформ не опубликован. Поэтому sites.list сохраняет все идентификаторы, возвращаемые Google, и указывает, соответствуют ли они документированному формату API. Остальные инструменты намеренно отклоняют недокументированные форматы, а не пытаются самостоятельно определить идентификатор. Пока Google не опубликует документацию о поддержке API, используйте интерфейс или экспорт Search Console для работы с ресурсом платформы.

Режим чтения и записи запрашивает области доступа Google Search Console для чтения и записи, а также Indexing API. Режим только для чтения запрашивает только https://www.googleapis.com/auth/webmasters.readonly (а также openid и email) и не регистрирует шесть инструментов записи и инструмент indexing.status для чтения: для последнего всё равно требуется отдельная область доступа Indexing API от Google. По умолчанию используется режим чтения и записи, чтобы сохранить текущее поведение существующих развёртываний. Инструкции по выбору режима до подключения пользователей приведены в SETUP.md.

Большие аналитические ответы ограничиваются на границе MCP, а не формируются целиком с последующим отбрасыванием клиентами из-за ограничений на структурированное содержимое. Инструменты, возвращающие списки, где это применимо, предоставляют параметры start_row и next_start_row. Инструменты ранжированной аналитики предоставляют параметры limit, start_row и метаданные result_page, включая has_more, truncated и byte_limit_reached. Если has_more имеет значение true, продолжайте постраничную загрузку и не считайте, что одного ответа достаточно.

Допуск к использованию Indexing API и одобрение Google. Indexing API от Google не предназначен для отправки любых страниц на индексацию: на момент написания этой документации Google указывает, что API поддерживает только два типа контента — страницы с разметкой JobPosting и страницы прямых трансляций с разметкой BroadcastEvent, вложенной в VideoObject. Перед вызовом indexing.request сервер загружает целевой URL и проверяет статическую разметку JSON-LD, Microdata и RDFa на наличие одного из этих типов. Если ни один из них не найден или страницу не удалось загрузить, сервер возвращает сообщение с объяснением, почему URL не подходит, и не вызывает Indexing API. Разметку, добавленную только после выполнения JavaScript на стороне клиента, нельзя подтвердить в ходе этой предварительной проверки, поэтому запрос отклоняется. Перед вызовом indexing.remove сервер проверяет другое условие удаления, установленное Google: URL должен возвращать HTTP 404/410 или содержать директиву noindex в метатеге robots. Уведомления об обновлении и удалении используют общую квоту на публикацию. Стандартная квота Google — 200 запросов на публикацию в день для проекта — предназначена для первоначальной настройки и тестирования отправки данных; для использования API за пределами этих целей требуется одобрение Google на использование API и выделение ресурсов. Google также проверяет каждую отправку на наличие спама и предупреждает, что злоупотребление API или попытки превысить квоты с помощью нескольких аккаунтов и другими способами могут привести к потере доступа. Успешный ответ на уведомление подтверждает только то, что Google его получил, но не гарантирует завершение индексации или удаления.

О чём можно спросить

После подключения задавайте ассистенту, например, такие вопросы:

  • «Какие 20 запросов получили больше всего кликов за последние 28 дней?»

  • «Сравни количество показов для example.com в этом месяце и прошлом. На каких страницах показатели снизились?»

  • «Как Google показывает проиндексированную версию страницы https://example.com/pricing? Укажи статус индексации и дату последнего сканирования.»

  • «У каких строк с запросами или страницами много показов, а средняя позиция составляет от 5 до 15? Покажи возможности для оптимизации.»

  • «Подготовь еженедельную сводку для sc-domain:example.com по состоянию на сегодня.»

  • «Есть ли ошибки или предупреждения в моих файлах Sitemap?»

  • «Используя предоставленный мной регулярный шаблон для бренда, приблизительно раздели клики на брендовые и небрендовые.»

  • «Как мой сайт показывает себя в Google Discover по сравнению с обычным поиском Google?»

Регулярные шаблоны запросов дают только приблизительную оценку. Встроенный фильтр Search Console для брендовых и небрендовых запросов использует собственную классификацию Google с поддержкой искусственного интеллекта: она учитывает языковые варианты, опечатки и связанные продукты и услуги. Этот классификатор недоступен в качестве фильтра Search Analytics API.

В Search Console также есть специальные отчёты о результатах в Generative AI для Search и Discover. В актуальной документации Search Analytics API не предусмотрен отдельный тип поиска или фильтр для Generative AI, поэтому этот MCP не пытается их угадывать. Данные AI Overviews и AI Mode по-прежнему входят в общую статистику эффективности поиска в интернете. Пока Google не документирует доступ к API для специального отчёта о Generative AI, используйте интерфейс Search Console.

По состоянию на 24 сентября 2026 года в интерфейсе Search Console также доступен фильтр эффективности мультимодального поиска в интернете. Он охватывает такие способы поиска, как Lens, Circle to Search, загрузка изображений и поиск по изображениям в Chrome. В актуальной версии Search Analytics API и документа Discovery по-прежнему указаны только типы поиска web, image, video, news, discover и googleNews. Поэтому этот MCP не добавляет несуществующий search_type: "multimodal" и не пытается угадать значение searchAppearance. Пока Google не документирует доступ к API, для отдельного анализа мультимодального поиска используйте интерфейс Search Console.

Подключение в AI-клиенте

После развёртывания сервера (см. SETUP.md) подключите его, вставив URL Worker с путём /mcp в свой клиент:

https://<your-worker>.workers.dev/mcp

  • Claude.ai / Claude Desktop — откройте Customize → Connectors, нажмите + → Add custom connector, укажите имя и вставьте URL с путём /mcp. Не заполняйте необязательные поля расширенных настроек OAuth Client ID/Secret. В тарифах Team и Enterprise сначала владелец или основной владелец должен добавить пользовательский Web-коннектор в разделе Organization settings → Connectors. После этого участники смогут подключить его через Customize → Connectors. При первом подключении Claude откроет процесс входа через Google.

  • Cursor — добавьте удалённый MCP-сервер с транспортом Streamable HTTP, указав тот же URL с путём /mcp. Cursor поддерживает OAuth для удалённых MCP-серверов с HTTP. Кнопка Add to Cursor выше использует локальную конечную точку npm launcher.

  • ChatGPT — включите Developer mode, затем создайте пользовательское MCP-приложение через Settings → Apps → Create. Администраторы и владельцы также могут воспользоваться разделом Workspace settings → Apps → Create. Укажите конечную точку /mcp, выберите подходящий способ аутентификации, нажмите Scan Tools, завершите OAuth-аутентификацию и создайте приложение. Полная поддержка MCP, включая инструменты записи и изменения данных, сейчас доступна в тарифах Business и Enterprise/Edu. В Pro доступны только пользовательские MCP-интеграции для чтения и получения данных, поэтому для этого режима установите GSC_ACCESS_MODE=readonly.

Конечная точка /mcp одинакова для всех клиентов, но у каждого хоста свой процесс настройки и выдачи разрешений.

Настройка

Для самостоятельного размещения сервера потребуются собственные учётные данные Google OAuth и аккаунт Cloudflare. Полная инструкция с командами для копирования и вставки приведена в SETUP.md. В ней также есть важное примечание о проверке OAuth-приложения Google и ограничении в 7 дней для refresh token, пока приложение не проверено.

Краткая последовательность действий:

git clone https://github.com/<you>/mcp-gsc.git
cd mcp-gsc
npm install
cp wrangler.example.jsonc wrangler.jsonc       # then paste in your KV ids
# set GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET / TOKEN_ENCRYPTION_KEY as secrets
# choose GSC_ACCESS_MODE=readonly in wrangler.jsonc for a read-only deployment
npm run deploy

Подробное описание каждого шага см. в SETUP.md.

Разработка

npm install
npm test              # typecheck + offline unit tests (what CI runs)
npm run dev           # wrangler dev (local)
npm run test:smoke    # structural smoke tests against a deployment

Будем рады вашим вкладам — см. CONTRIBUTING.md.

Лицензия

MIT © 2026 DigestSEO.

Создан и поддерживается Tomi Šeregi, автором DigestSEO — набора инструментов SEO с открытым исходным кодом и программного обеспечения для анализа видимости в поиске.