Google Search Console MCP

Open source · Сентябрь 2026. Кейс описывает версию 1.0.0 на опубликованном коммите ab9a7ba0. Ссылки на реализацию закреплены на этой версии.

Задача: дать SEO Agent доступ к данным Google

Для своего SEO Agent я собираю историю поисковых показателей и изменений страниц. Google Search Console — один из источников этой системы: он знает о показах, кликах, запросах и том, как Google видит URL. Чтобы агент мог получать эти сведения по запросу, я сделал отдельный MCP-сервер на Go.

Задача интеграции шире передачи HTTP-ответа. Агенту нужно выбрать правильный ресурс, сохранить период и группировку отчёта, отличить неполные данные от нулей и показать, откуда взялась рекомендация. Хранение истории и расписание остаются у SEO Agent; сам GSC MCP отвечает за доступ к Search Console.

Сценарий: выбрать страницы для дальнейшего анализа

1. list_sites возвращает доступные ресурсы и уровень доступа. Агент использует siteUrl из ответа: sc-domain:example.com и ресурс с URL-префиксом имеют разный смысл.
2. query_analytics получает показы, клики, CTR и среднюю позицию за явно выбранный период с группировкой по странице или запросу.
3. inspect_url позволяет изучить сведения Google об отдельной странице: вердикт, состояние обхода и канонические URL. list_sitemaps дополняет картину картами сайта.

Полезный запрос агенту: «Выбери ресурс из list_sites. Сравни два одинаковых по длине завершённых периода с одинаковыми фильтрами. Покажи страницы, у которых изменились показы и клики, и отдельно перечисли ограничения данных». После этого можно выбирать URL для проверки. Изменение CTR само по себе ещё не объясняет причину изменения трафика.

Решение 1: четыре операции чтения с явным контрактом

В MCP-каталоге четыре инструмента: список ресурсов, аналитика, проверка URL и sitemap. Каждый публикует входную схему, схему результата и аннотации чтения. В сервере нет инструментов удаления ресурса или отправки URL на индексирование. Это соответствует роли планового сборщика.

MCP-обработчики зависят от небольшого интерфейса gsc.Console. Реальный клиент и синтетическое демо реализуют одну границу. Поэтому можно проверить аргументы и поведение протокола без Google-ключа, а отдельно — преобразование внешнего API. Регистрация и обработчики инструментов.

Решение 2: сохранить календарь и неполноту аналитики

Даты Search Analytics относятся к Pacific Time с переходом на летнее время. Сервер рассчитывает значения по умолчанию в этом календаре: 28 дней с окончанием вчера, dataState=final. В ответе остаются фактические даты, измерения и состояние данных. Для свежих данных сохраняется метаинформация о неполноте, если Google её вернул.

Есть пагинация через startRow и подсказки mayHaveMore/nextStartRow. Но Google не гарантирует полную выдачу всех строк. Поэтому переход по страницам ответа не превращает отчёт в исчерпывающую выгрузку. Эти ограничения зафиксированы и в контракте Search Analytics API.

Отдельные тесты проверяют границы суток и переходы времени, сохранение firstIncompleteDate, смещение следующей страницы и отклонение несовместимых параметров до внешнего запроса. Проверки календаря и контракта аналитики.

Решение 3: ограничить весь путь запроса

Стандартный бюджет обращения к Google — 30 секунд, включая очередь, OAuth и повторы. По умолчанию один процесс допускает восемь параллельных операций, а ответ Google ограничен 8 MiB. Отмена запроса охватывает ожидание свободного слота и внешнее обращение.

Временные ошибки чтения могут повторяться в пределах общего бюджета. Постоянная ошибка доступа требует исправления настройки. Наружу возвращается классифицированная ошибка с признаком возможности повтора, без сырого сообщения Google и ключевого материала. Тесты повторов, отмены, OAuth и размера ответа.

Что проверено

При подготовке кейса прошли тесты пакетов internal/gsc, internal/mcpserver и cmd/mcp-server на указанном коммите. Изолированное нативное демо прошло встроенный smoke: list_sites, query_analytics, inspect_url, list_sitemaps. Дополнительный вызов через HTTP подтвердил показанный выше ответ.

Интеграционный тест проходит через настоящий MCP SDK и HTTP с подставным внешним API. Это проверка транспорта, доступа и преобразований. Рост поискового трафика и пропускную способность сервиса в этом кейсе я не измеряю.

Границы решения

Одна установка использует один сервисный аккаунт. Многопользовательского OAuth-входа и изоляции пользователей внутри процесса нет. Для несвязанных владельцев сайтов нужны отдельные установки. Ограничитель параллелизма локальный: несколько реплик увеличивают суммарную нагрузку на квоты Google.

inspect_url возвращает сохранённые Google сведения об индексе и не выполняет живой обход страницы. Сам MCP не хранит историю, не запускается по расписанию и не гарантирует наличие свежих финальных строк. В связке с Webmaster MCP и ahref каждый источник сохраняет собственный смысл данных.

Как попробовать

Для Docker-демо не нужен Google-аккаунт. В примере выбран порт 18088, чтобы его можно было запустить рядом с другим MCP:

git clone https://github.com/tenqz/google-search-console-mcp.git
cd google-search-console-mcp
HTTP_PORT=18088 docker compose -f compose.demo.yml up -d --build
docker compose -f compose.demo.yml exec mcp /mcp-server --smoke http://127.0.0.1:8080/mcp

Подключи HTTP-клиент к http://localhost:18088/mcp с Authorization: Bearer demo-token. Стоп: HTTP_PORT=18088 docker compose -f compose.demo.yml down. Для рабочего аккаунта нужны ключ сервисного аккаунта, разрешение на конкретный ресурс Search Console и отдельный MCP-токен. Инструкция установки и использования и настройка доступа Google.