gsc-mcp-connector

Самостоятельно размещаемый MCP-сервер для Google Search Console, развёртываемый на Cloudflare Workers за 15 минут. Подключайте его к ChatGPT, Claude или любому клиенту, поддерживающему MCP, и запрашивайте данные GSC на естественном языке.

Что вы получаете

После развёртывания вы получаете собственный MCP-эндпоинт, предоставляющий 4 инструмента вашему ИИ-ассистенту:

• list_sites — просмотр всех свойств, доступных аутентифицированному пользователю

• query_search_analytics — клики, показы, CTR, позиция; фильтрация по запросу / странице / стране / устройству / типу поиска / дате

• inspect_url — полный вывод API URL Inspection (статус индексации, канонический адрес, мобильная версия, AMP)

• list_sitemaps — все отправленные карты сайта и статус их обработки

Вы спрашиваете: «Какие 50 запросов показали наибольшую потерю кликов за последние 28 дней по сравнению с предыдущими 28 днями?» — ассистент загружает данные, вычисляет разницу и пишет анализ. Никаких экспортов в SQL.

Related MCP server: gsc-mcp-connector

Как это работает

ChatGPT/Claude  ──OAuth──▶  Your Worker  ──OAuth──▶  Google
                                 │
                                 └─ holds your Google refresh_token
                                    (encrypted, in OAuth grant props)

Два потока OAuth:

1. MCP-клиент → Worker: ChatGPT/Claude выполняют OAuth 2.1 + PKCE против вашего Worker. Интерфейс входа запрашивает статический «ключ доступа», который вы задаёте при развёртывании (шлюз коннектора).

2. Worker → Google: после проверки ключа доступа пользователь перенаправляется на экран согласия Google для предоставления разрешения webmasters.readonly. Полученный refresh-токен сохраняется в OAuth-гранте; при каждом вызове инструмента Worker обновляет свежий access-токен и обращается к GSC.

Доступ управляется аккаунтом Google пользователя — никаких сервисных аккаунтов, танцев с управлением пользователями GSC и задержек распространения прав.

Необходимые условия

Бесплатного тарифа Cloudflare Workers (100 000 запросов/день) вполне достаточно для личного SEO-использования. Платный план Cloudflare не требуется.

Быстрый старт (~15 минут)

1. Разверните Worker

Нажмите кнопку Deploy to Cloudflare в верхней части этого README. Cloudflare клонирует репозиторий в ваш аккаунт, установит зависимости и выдаст публичный URL вида https://gsc-mcp-connector.<ваш-поддомен>.workers.dev.

Примечание: на этом этапе вас попросят указать MCP_BEARER_TOKEN, GOOGLE_OAUTH_CLIENT_ID и GOOGLE_OAUTH_CLIENT_SECRET. Google-параметров у вас пока нет — введите в MCP_BEARER_TOKEN любую случайную строку (её можно изменить позже), а в поля Google — что угодно. Корректные значения мы установим на шаге 4.

Если вы предпочитаете обойтись без кнопки, клонируйте репозиторий локально, выполните npm install, затем npx wrangler deploy.

После развёртывания запомните URL вашего Worker. Он понадобится на шагах 3 и 5.

2. Сгенерируйте ключ доступа коннектора

Это статическая случайная строка, используемая как шлюз перед Google OAuth. Любой, кто использует коннектор, должен вставить эту строку в интерфейсе входа.

openssl rand -hex 32

Сохраните вывод — вы установите его как секрет и будете использовать в ChatGPT/Claude.

3. Настройте Google Cloud (OAuth-клиент)

Следуйте пошаговой инструкции в docs/SETUP_GCP.md. Используйте URL вашего Worker с шага 1 в поле Authorized redirect URI. В результате вы получите Client ID и Client Secret.

Это самый длинный шаг (~10 минут в первый раз), но он выполняется только один раз.

4. Настройте секреты Worker

npx wrangler secret put MCP_BEARER_TOKEN
# paste the value from step 2

npx wrangler secret put GOOGLE_OAUTH_CLIENT_ID
# paste the Client ID from step 3

npx wrangler secret put GOOGLE_OAUTH_CLIENT_SECRET
# paste the Client Secret from step 3

Или через панель управления Cloudflare: Workers & Pages → ваш worker → Settings → Variables and Secrets → добавьте каждый как тип Secret.

Совет — проблема с кодировкой в Windows: если вы передаёте содержимое файла через конвейер (например, Get-Content | wrangler secret put) и в этом файле есть BOM для UTF-8, BOM попадёт в ваш секрет и нарушит парсинг JSON. Панель управления Cloudflare или интерактивный режим wrangler secret put (вставка в ответ на приглашение) полностью избегают этой проблемы.

5. Подключитесь к ChatGPT (Plus/Pro/Team)

ChatGPT → Settings → Connectors → Add custom connector:

• Name: gsc

• MCP Server URL: https://YOUR-WORKER-URL/mcp (обязательно заканчивается на /mcp)

• Authentication: OAuth

• Отметьте «I understand and want to continue»

• Create

Откроется всплывающее окно с интерфейсом входа на вашем Worker. Вставьте ваш MCP_BEARER_TOKEN → нажмите Continue with Google → Google попросит вас войти (используйте аккаунт, которому принадлежит ваше свойство GSC) и предоставить разрешение webmasters.readonly → вы будете перенаправлены обратно в ChatGPT, коннектор активен.

В новом чате включите коннектор gsc на панели инструментов, затем спросите: «Список моих сайтов в Google Search Console». Вы должны увидеть свои свойства.

6. (Необязательно) Подключитесь к Claude.ai (Pro/Team)

Settings → Integrations → Add custom integration → тот же URL, та же процедура.

Локальная разработка

git clone https://github.com/JuJu78/gsc-mcp-connector
cd gsc-mcp-connector
npm install
cp .dev.vars.example .dev.vars
# edit .dev.vars with your real Client ID + Client Secret + bearer token
npx wrangler dev

Сервер разработки запускается на http://localhost:8787. Обратите внимание: локальная разработка не может полностью завершить поток Google OAuth, поскольку redirect URI Google требуют HTTPS. Для настоящего сквозного тестирования разверните на Cloudflare и тестируйте через URL workers.dev.

Ограничения

• Только чтение. Добавление операций записи (отправка карты сайта, запрос индексации) намеренно исключено — они рискованны в контексте LLM. Откройте PR, если они вам нужны.

• Однотенантный по замыслу. Один оператор развёртывает, один bearer-токен защищает коннектор, доступ привязан к тому, кто проходит процедуру Google OAuth. Мультитенантный SaaS-подход не входит в рамки.

• Экран согласия OAuth в режиме Testing ограничивает вас 100 тестовыми пользователями (более чем достаточно для личного/командного использования). Для более широкого распространения потребуется отправить приложение на проверку Google (область webmasters.readonly считается «чувствительной» и требует ручной проверки).

• Квоты API GSC — 1200 запросов/мин/проект, 30 000/день. Вполне достаточно для интерактивного использования.

• Диапазон дат — GSC возвращает данные за последние 16 месяцев. Более ранние даты приводят к ошибке.

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

Стек

• Cloudflare Workers + Durable Objects (через SDK agents ≥0.12)

• @cloudflare/workers-oauth-provider для OAuth 2.1 + DCR + PKCE

• @modelcontextprotocol/sdk для определений инструментов

• Пространство имён KV OAUTH_KV для состояния OAuth

• Поток Google OAuth 2.0, подписанный нативно через Web Crypto API (без зависимостей Node)

Благодарности

Создано Julien Gourdon — SEO-консультантом, исследующим пересечение поиска и ИИ.

Лицензия

MIT — см. LICENSE.