gsc-ga4-mcp

Небольшой локальный MCP-сервер, который даёт Claude Code доступ только для чтения к Google Search Console и GA4, а также несколько инструментов, которые связывают оба набора данных.

Проблема

SEO-работа в ИИ-ассистенте обычно означает экспорт CSV из Search Console, экспорт ещё одного CSV из GA4, вставку обоих в чат и повторение этого каждый раз, когда нужна свежая цифра. Эти два набора данных также никогда не совпадают сами по себе: Search Console знает показы, клики и CTR; GA4 знает сессии, вовлечённость и конверсии. Чтобы ответить на вопрос «какие страницы получают трафик, но тратят его впустую», приходится объединять их по URL вручную.

Google публикует официальный MCP-сервер для Analytics, но он не охватывает Search Console. Серверы Search Console от сообщества существуют, но когда данные принадлежат клиентам, запуск небольшой обёртки, которую вы можете прочитать насквозь, лучше, чем доверять чужому.

Этот сервер напрямую вызывает официальные Google API, использует права только на чтение и работает с вашей собственной машины.

Related MCP server: Google Search Console MCP Server

Возможности

Двадцать MCP-инструментов поверх stdio.

Search Console

GA4

Совместный анализ

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

project_mappings и project_lookup читают локальный файл, в котором имя проекта или клиента сопоставляется с ресурсом (property) GSC и ресурсом GA4. Поэтому можно сказать «сопоставь GSC и GA4 для example.com»``, а не помнить значение properties/123456789`.

Стек

Node.js + TypeScript. @modelcontextprotocol/sdk для сервера, google-auth-library для авторизации, zod для схем инструментов. Никакой базы данных, никакого удалённого бэкенда и телеметрии — процесс работает локально, а Claude Code запускает его через stdio.

Все области доступа — только на чтение, и на этом весь набор разрешений заканчивается:

• https://www.googleapis.com/auth/webmasters.readonly

• https://www.googleapis.com/auth/analytics.readonly

Учётные данные находятся вне репозитория, по умолчанию — в ~/.config/gsc-ga4-mcp/.

Установка

1. Установка

git clone https://github.com/YOUR_USER/gsc-ga4-mcp.git
cd gsc-ga4-mcp
npm install
npm run build
mkdir -p ~/.config/gsc-ga4-mcp

2. Включение API

В Google Cloud Console создайте или выберите проект и включите:

• Google Search Console API

• Google Analytics Data API

• Google Analytics Admin API

3. Создание учётных данных OAuth

В разделе APIs & Services → OAuth consent screen настройте экран согласия OAuth. Выбирайте External, если управляемые вами ресурсы не собраны в одном Google Workspace, и добавьте свой адрес электронной почты как тестового пользователя, пока приложение находится в режиме тестирования.

В разделе APIs & Services → Credentials создайте идентификатор OAuth-клиента типа Desktop app, скачайте JSON и сохраните его как ~/.config/gsc-ga4-mcp/oauth-client.json.

Для работы с клиентами, где нужна изоляция прав по аккаунтам, используйте вместо этого сервисный аккаунт и добавьте его адрес в каждый ресурс GSC и GA4 с правом доступа на чтение. Установите GOOGLE_AUTH_MODE=service_account и укажите в GOOGLE_SERVICE_ACCOUNT_KEY_FILE путь к ключу.

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

cp .env.example .env
cp projects.example.json ~/.config/gsc-ga4-mcp/projects.json

Пути в .env должны быть абсолютными — символ ~ не раскрывается.

GOOGLE_AUTH_MODE=oauth
GOOGLE_OAUTH_CREDENTIALS_FILE=/Users/YOUR_USER/.config/gsc-ga4-mcp/oauth-client.json
GOOGLE_TOKEN_PATH=/Users/YOUR_USER/.config/gsc-ga4-mcp/token.json
GOOGLE_OAUTH_REDIRECT_URI=http://127.0.0.1:3000/oauth2callback
PROJECTS_CONFIG=/Users/YOUR_USER/.config/gsc-ga4-mcp/projects.json
MCP_DEFAULT_GSC_SITE=sc-domain:example.com
MCP_DEFAULT_GA4_PROPERTY=properties/123456789
MAX_ROWS=25000

Сопоставление проектов (projects.json):

{
  "projects": [
    {
      "name": "My Site",
      "client": "Internal",
      "domain": "example.com",
      "gscSiteUrl": "sc-domain:example.com",
      "ga4Property": "properties/123456789",
      "notes": "Replace with the real GA4 property ID."
    }
  ]
}

5. Авторизация

npm run auth

Скрипт запускает прослушивание на 127.0.0.1:3000 и выводит URL Google. Откройте его, одобрите права только для чтения, и токен будет записан в путь, указанный в GOOGLE_TOKEN_PATH.

6. Регистрация в Claude Code

claude mcp add google-seo -- node /ABSOLUTE/PATH/TO/gsc-ga4-mcp/dist/index.js
claude mcp list

Или добавьте .mcp.json в репозиторий проекта, где нужны инструменты (см. .mcp.example.json):

{
  "mcpServers": {
    "google-seo": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gsc-ga4-mcp/dist/index.js"],
      "env": {
        "GOOGLE_AUTH_MODE": "oauth",
        "GOOGLE_OAUTH_CREDENTIALS_FILE": "/Users/YOUR_USER/.config/gsc-ga4-mcp/oauth-client.json",
        "GOOGLE_TOKEN_PATH": "/Users/YOUR_USER/.config/gsc-ga4-mcp/token.json",
        "PROJECTS_CONFIG": "/Users/YOUR_USER/.config/gsc-ga4-mcp/projects.json",
        "MCP_DEFAULT_GSC_SITE": "sc-domain:example.com",
        "MCP_DEFAULT_GA4_PROPERTY": "properties/123456789"
      }
    }
  }
}

Регистрацию через CLI используйте, если предпочитаете не хранить пути и значения по умолчанию для ресурсов в репозитории.

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

Задавайте запрос обычным языком — Claude выберет нужные инструменты сам.

Use gsc_list_sites and ga4_list_properties. Give me a table of the GSC sites
and GA4 properties I can reach.

Analyse organic traffic for sc-domain:example.com over the last 90 days using
gsc_top_queries and gsc_top_pages.

Cross GSC and GA4 for example.com over the last 90 days. Find pages with high
impressions and low CTR, and rank the opportunities by likely impact.

Run seo_opportunity_report and group the output into quick wins, pages that
need a rewrite, and pages that miss search intent.

Inspect https://www.example.com/page/ with gsc_url_inspection and tell me
whether Google has it indexed.

Эксплуатационные заметки

• Не храните .env, token.json, projects.json и ключи сервисного аккаунта в системе контроля версий. Поставленный по умолчанию .gitignore уже включает их.

• Данные клиентской аналитики конфиденциальны. Не вставляйте полные выгрузки в инструменты, которые клиент не одобрил.

• Отзывайте токен или сервисный аккаунт по завершении работы с клиентом.

• MAX_ROWS ограничивает размер ответа. Уменьшите его значение, если ответы становятся слишком громоздкими.

Поиск и устранение неисправностей

• Claude Code не видит инструменты. Выполните claude mcp list, а затем /mcp внутри Claude Code.

• Ошибки токена OAuth. Повторно запустите npm run auth и проверьте, что GOOGLE_TOKEN_PATH — абсолютный путь.

• access_denied. Пока приложение в режиме тестирования, добавьте свой адрес как тестового пользователя на экране согласия OAuth.

• Домен отсутствует в GSC. Учётным данным нужен доступ именно к этому ресурсу: sc-domain:example.com и https://www.example.com/ — это разные ресурсы.

• Ресурс отсутствует в GA4. Пользователю или сервисному аккаунту нужна роль не ниже Viewer на аккаунте или ресурсе.

• gsc_url_inspection не работает. inspectionUrl должен находиться внутри siteUrl, а ресурсы с URL-префиксом должны заканчиваться на /.

• Недопустимые метрики GA4. Используйте официальные яназвания измерений и метrik GA4; runReport отклоняет всё остальное.

Ссылки

• Claude Code MCP документация

• Model Context Protocol

• Search Console API

• GA4 Data API

• Google Analytics Admin API

• Google OAuth scopes

Лицензия

MIT. См. LICENSE.