seo-analytics-mcp

Google Search Console, GA4 и IndexNow — как MCP-сервер.

Спрашивайте Claude о своих сайтах. Что в топе, что изменилось, что проиндексировано, что конвертирует.

"Which pages lost the most clicks in the last 28 days versus the 28 before?"
"How is /pricing doing?"
"Is https://example.com/new-post indexed yet?"
"Which pages rank on page one but get almost no clicks?"
"Top 20 queries for the blog last month, and which of them convert in GA4."

Вы авторизуете свою собственную учётную запись Google через OAuth-клиент в своём собственном проекте Google Cloud. Ничто в вашем доступе не проходит через кого-то ещё: этот репозиторий не содержит учётных данных, и каждая квота Google, которую вы тратите, — ваша собственная.

Содержание

Установка · Настройка · Проблема семи дней · Инструменты · Формат ответа · Конфигурация · Запись · Профили · Дизайн · Устранение неполадок · Разработка

Related MCP server: GSC Analyst Connector

Установка

Требуется Python 3.10+ и uv.

uvx seo-analytics-mcp doctor      # no install needed — prints your setup steps, in order

doctor — это весь процесс адаптации. Он точно говорит, чего не хватает и что запустить дальше, на каждом этапе. Если вы больше ничего здесь не читаете — запустите его.

Настройка

Шесть кликов в консоли Google Cloud, затем одна команда. Десять минут, один раз.

Создайте проект Google Cloud — или используйте существующий. console.cloud.google.com/projectcreate

Включите API. Search Console обязателен; пара GA4 — опциональна.

searchconsole · analyticsdata · analyticsadmin

Настройте экран согласия, затем нажмите «Опубликовать приложение». console.cloud.google.com/auth/overview

Выберите External и опубликуйте. Вы — единственный пользователь своего приложения, поэтому применяется исключение Google для личного использования, и проверка не требуется. Пользователи Workspace могут выбрать Internal вместо этого.

Не пропускайте шаг «Опубликовать» — см. ниже.

Создайте OAuth-клиент типа Desktop app и скачайте JSON. console.cloud.google.com/auth/clients

Клиент Web application не может выполнить loopback-редирект, который нужен этому серверу. doctor проверяет именно эту ошибку, потому что её легко допустить.

Авторизуйтесь один раз из терминала:

uvx seo-analytics-mcp auth --client-secret ~/Downloads/client_secret_*.json

Откроется ваш браузер. Google скажет «Google hasn't verified this app» — это ожидаемо для вашего собственного клиента: Advanced → Continue. Токен сохраняется в вашем каталоге профиля с правами 0600.

Проверьте, затем подключите:

uvx seo-analytics-mcp doctor      # eleven checks; exit 0 means it will work

Подключение

claude mcp add seo \
  -e GSC_DEFAULT_SITE=sc-domain:example.com \
  -e GA4_DEFAULT_PROPERTY=properties/123456789 \
  -- uvx seo-analytics-mcp

{
  "mcpServers": {
    "seo": {
      "command": "uvx",
      "args": ["seo-analytics-mcp"],
      "env": {
        "GSC_DEFAULT_SITE": "sc-domain:example.com",
        "GA4_DEFAULT_PROPERTY": "properties/123456789"
      }
    }
  }
}

Затем полностью завершите работу Claude Desktop (⌘Q — закрытие окна недостаточно) и откройте заново.

[!NOTE] В этой конфигурации нет пути к учётным данным. Токен хранится в каталоге профиля, который записал seo-mcp auth, поэтому весь блок можно безопасно вставлять в issue на GitHub.

Проблема семи дней

[!WARNING] Если сервер работает, а затем примерно через неделю перестаёт — причина в этом.

Google выдаёт refresh-токены, которые истекают через семь дней для любого внешнего OAuth-приложения, статус публикации которого всё ещё Testing. Очевидный путь настройки — создать проект, создать клиент, добавить себя как тестового пользователя — оставляет вас в этом состоянии.

Исправление — один клик: на экране согласия установите аудиторию External и нажмите Publish app. Затем uvx seo-analytics-mcp auth --reauth.

doctor отмечает токен, который достаточно свеж, чтобы всё ещё быть Testing-токеном, а каждая ошибка invalid_grant от сервера объясняет это полностью. Это не баг сервера — но это будет самая частая проблема, о которой сообщают.

Инструменты

Тринадцать инструментов: десять соответствуют операциям вышестоящего API, два объединяют источники, и один существует только для того, чтобы модель могла подсказать растерявшемуся пользователю, что делать.

Как выглядит ответ

Каждый инструмент чтения возвращает одни и те же четыре ключа. Ограниченный, самодокументируемый и несущий собственные оговорки.

{
  "summary": {
    "source": "gsc",
    "rows_returned": 10,        // what you see
    "rows_matched": 1847,       // what exists upstream
    "date_range": "2026-07-29..2026-08-25",   // resolved, always echoed
    "data_state": "final",
    "totals": { "clicks": 4730, "impressions": 512903, "ctr": 0.0092, "position": 12.4 }
  },
  "rows": [ /* capped at min(row_limit, 1000) */ ],
  "notes": [
    "Google anonymises rare queries: these rows do NOT sum to property totals.",
    "dataState=final excludes the most recent 2-3 days.",
    "1837 further rows were not included inline."
  ],
  "export": "~/.../exports/a1b2c3.csv"        // only when rows spilled
}

Три соглашения действуют везде:

Итоги охватывают все полученные строки, а не только показанные — модель, которая видит десять строк и итог по десяти, не может отличить усечение от реальности. Показатели никогда не усредняются: ctr пересчитывается как клики ÷ показы, position взвешивается по показам, engagementRate — это вовлечённые сеансы ÷ сеансы.

Оговорки путешествуют вместе с данными. Тот слой, который знает об оговорке, добавляет её: клиент знает, что было запрошено измерение query, shape() знает, сколько строк он отбросил, GA4 знает, что ответ был сэмплирован. Одних docstring недостаточно — они теряются именно тогда, когда модель смотрит на цифры.

Ошибки называют решение. Ошибка 403 говорит, какой грант проверить и где, — никогда не сырое тело ошибки Google.

The authorised Google account has no access to sc-domain:example.com. Confirm the
account you authorised is the one with access — Search Console grants are per-property
under Settings > Users and permissions, GA4 grants are per-property under Admin >
Property access management. If access was added recently, run `seo-mcp auth --reauth`.

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

Каждая переменная необязательна. Приоритет: аргумент инструмента → переменная окружения → config.json профиля.

Даты

Каждый аргумент даты принимает YYYY-MM-DD, today, yesterday или NdaysAgo. Ответы отражают фактический использованный абсолютный диапазон, потому что модель, которая неверно угадывает сегодняшнюю дату, даёт пустой результат, который читается как «трафик упал до нуля».

Search Console отстаёт на 2–3 дня и хранит данные ~16 месяцев; диапазоны вне этих границ помечаются или отклоняются, а не молча возвращают пустоту. GA4 отчитывается в часовом поясе свойства, поэтому его даты не совпадают точно с датами Search Console — ответы говорят об этом там, где это важно.

Запись

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

[!IMPORTANT] Один только флаг confirm — не механизм безопасности: это аргумент, который заполняет модель, и та же ошибка чтения, которая приводит к неверным URL, приводит и к confirm=true рядом с ними.

Токен невозможно подделать без пробного запуска, и измените один URL — и он перестанет совпадать. Оба инструмента также несут аннотации destructiveHint, поэтому клиент, который ограничивает разрушительные инструменты собственным запросом подтверждения, сделает это.

Области доступа только для чтения — по умолчанию. Незнакомец, устанавливающий SEO-инструмент, который сразу просит разрешение изменять свойства Search Console, обоснованно откажется.

Профили

Несколько учётных записей Google на одной машине — для агентств, которые держат клиентские свойства рядом.

uvx seo-analytics-mcp auth --profile client-a --client-secret ./client-a.json
uvx seo-analytics-mcp auth --profile client-b --client-secret ./client-b.json
uvx seo-analytics-mcp profiles list

Установите SEO_MCP_PROFILE для каждой записи MCP-сервера. Ключи кэша включают профиль, поэтому две учётные записи никогда не смогут обслуживать данные друг друга.

Профиль — это один каталог — первое, что вы когда-либо попросите пользователя удалить:

uvx seo-analytics-mcp profiles rm client-a --yes

Они находятся в ~/Library/Application Support/seo-mcp/ (macOS), $XDG_CONFIG_HOME/seo-mcp/ (Linux) или %APPDATA%\seo-mcp\ (Windows).

Дизайн

Четыре слоя, строго сверху вниз. Если сделать это неправильно, поток авторизации окажется внутри вызова инструмента — это тот сбой, для предотвращения которого и существует весь дизайн.

flowchart TD
    subgraph L4["Entry points"]
        S[server.py<br/><i>MCPServer, stdio</i>]
        C[cli.py<br/><i>auth · doctor · profiles · serve</i>]
    end
    subgraph L3["Tools — argument surface, docstrings, cache policy"]
        T[13 handlers<br/><i>no HTTP, no credentials, no row shaping</i>]
    end
    subgraph L2["Clients — the only modules that speak HTTP"]
        G[gsc.py]
        A[ga4.py]
        I[indexnow.py]
    end
    subgraph L1["Leaves — importable by anyone, import nobody"]
        LV[shaping · errors · config · cache · auth/store · auth/scopes]
    end
    F[auth/flow.py<br/><i>loopback + PKCE · opens a browser</i>]

    S --> T
    C --> T
    C -.->|only reachable from here| F
    T --> G & A & I
    G & A & I --> LV

Поток браузера никогда не должен выполняться внутри вызова инструмента. MCP-инструмент, который блокирует stdio в ожидании, пока человек завершит экран согласия, выглядит как зависший сервер, и модель ничем не может помочь. Одна команда CLI, запущенная один раз, — вот и вся разница — и тест обходит AST каждого модуля, чтобы это обеспечить.

Другие правила, которые тесты проверяют механически: shaping.py не импортирует ни одной библиотеки Google (поэтому логика строк полностью юнит-тестируема без учётных данных), инструменты не импортируют HTTP-библиотек, и ничто на серверном пути не вызывает print() — на stdio-транспорте stdout несёт JSON-RPC, и один случайный print портит поток.

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

Каждый отчёт о проблеме должен включать seo-mcp doctor --json. Он не содержит учётных данных — только пути, версии, какие проверки прошли и какие API ответили.

Development

uv sync --extra dev
uv run pytest -q                    # 147 tests · no credentials · no network
uv run python scripts/smoke.py      # drives the server over real stdio JSON-RPC
uv run ruff check src tests

python3 -m venv .venv && ./.venv/bin/pip install -e ".[dev]"
./.venv/bin/python -m pytest -q
./.venv/bin/python scripts/smoke.py ./.venv/bin/seo-mcp

scripts/smoke.py запускает сервер как подпроцесс, выполняет рукопожатие MCP, перечисляет инструменты и вызывает несколько из них — используя временный каталог профиля, так что ваш настоящий токен не затрагивается. Это самый быстрый способ убедиться, что протокольная часть работает до появления каких-либо учётных данных Google.

Чтобы вручную поэкспериментировать, MCP Inspector не требует ничего, кроме Node:

npx @modelcontextprotocol/inspector ./.venv/bin/seo-mcp            # web UI
npx @modelcontextprotocol/inspector --cli ./.venv/bin/seo-mcp \
    --method tools/call --tool-name auth_status                    # scriptable

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

Две вещи, которые он не будет делать

[!NOTE] IndexNow не достигает Google. Участники: Bing, Yandex, Naver, Seznam.cz, Yep и Amazon — одна конечная точка распространяет данные на всех них. Google не участвует, а собственный Indexing API Google принимает только страницы со структурированными данными JobPosting или BroadcastEvent. Если вы устанавливаете это, ожидая более быстрой индексации в Google, вы будете разочарованы.

[!NOTE] Строки запросов никогда не суммируются в итоги. Google анонимизирует редкие запросы, поэтому любая разбивка по измерению query занижает данные. Каждый ответ, содержащий это измерение, повторяет предупреждение, потому что модель, получившая эти строки, иначе будет уверенно вычислять неверные проценты.

Вклад

Приветствуются issues и pull requests. Тестовый набор без учётных данных запускается при каждом push на Linux, macOS и Windows на Python 3.10 и 3.13 — если он проходит локально, он пройдёт и в CI.

Переименование инструмента или изменение аргумента ломает все сохранённые подсказки пользователя. Такие изменения вносятся в CHANGELOG.md и являются минорным обновлением до 1.0, мажорным после.

Лицензия

MIT.