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 (статус индексации, канонический URL, мобильная версия, AMP)

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

Вы спрашиваете: "Какие мои 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 token сохраняется в OAuth-гранте; при каждом вызове инструмента Worker обновляет свежий access token и вызывает GSC.

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

Предварительные требования

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

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

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

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

Примечание: на этом этапе вас попросят указать MCP_BEARER_TOKEN, GOOGLE_OAUTH_CLIENT_ID и GOOGLE_OAUTH_CLIENT_SECRET. У вас пока нет значений от Google — заполните MCP_BEARER_TOKEN любой случайной hex-строкой (потом можно изменить), а в поля 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 в панели инструментов, затем спросите: "List my Google Search Console sites". Вы должны увидеть свои свойства.

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, поскольку URI перенаправления Google требуют HTTPS. Для полноценного сквозного тестирования разверните на Cloudflare и тестируйте через URL workers.dev.

Ограничения

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

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

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

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

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

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

Стек

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

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

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

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

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

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

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

Лицензия

MIT — см. LICENSE.