XMLRiver MCP Toolkit

XMLRiver MCP Toolkit

Поисковая выдача Google и Яндекса, частотность запросов Wordstat и проверка позиций сайта — прямо в вашем AI-помощнике.

Подключите инструмент к Claude, Codex или Cursor и ставьте задачи обычным языком. Помощник обратится к XMLRiver и вернёт данные: запросы, частотности, позиции и ссылки. Фразы можно вставить прямо в чат. Создавать CSV и YAML вручную для работы через MCP не нужно. Если инструмент уже подключён и отвечает, переходите к примерам ниже: повторная установка не требуется.

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

Что умеет

Задача	Что получите
Подобрать запросы в Wordstat	Расширения исходной фразы с частотностью; по желанию — похожие запросы
Посмотреть динамику спроса	Данные Wordstat за выбранный период
Собрать выдачу	Ссылки и заголовки результатов Google или Яндекса для нужного региона и устройства
Найти сайт в выдаче	Все найденные вхождения домена и их позиции среди органических результатов
Снять позиции по списку фраз	Результаты, история прогонов и обновлённый CSV
Сравнить регионы	Выдача по каждой связке «фраза × регион × поисковик» и совпадения с ожидаемыми доменами
Проверить счёт	Баланс XMLRiver и стоимость запросов для Google и Яндекса

Как пользоваться после подключения

Напишите помощнику задачу обычным языком. Укажите сайт, поисковик, регион, устройство и нужную глубину проверки. Список фраз вставьте в то же сообщение.

Проверь позиции example.org в Яндексе и Google по Москве, мобильная выдача, первые пять страниц. Фразы:

• кофемашина для дома
• купить кофемашину
• ремонт кофемашин

Покажи таблицу: фраза, поисковик, позиция и найденная ссылка. Если сайт не найден, укажи фактически проверенную глубину.

Помощник сам обращается к XMLRiver по каждой фразе и собирает ответ. Можно попросить подобрать семантику, сравнить выдачу или посмотреть сезонность спроса. Дополнительные примеры есть ниже.

Что выполняется автоматически

MCP даёт помощнику четыре инструмента: баланс, подбор фраз Wordstat, историю спроса и поисковую выдачу. Помощник выбирает инструмент, передаёт параметры и объясняет результат. Один вызов выдачи обрабатывает одну фразу; список обрабатывается несколькими вызовами.

Для большого сбора с кэшем, историей и сохранением результатов в пакете есть отдельная команда. Если помощнику доступен терминал и запись файлов, попросите его выполнить весь сбор:

Сними позиции example.org по этому списку в Яндексе по Москве, мобильная выдача, глубина 50. Используй пакетный сбор XMLRiver с лимитом 100 HTTP-попыток. Сам подготовь нужные файлы, сначала покажи объём задания, затем запусти сбор и сохрани результат.

В таком режиме помощник сам готовит CSV или YAML и запускает команду. Если клиент умеет только вызывать MCP, используйте обычную проверку фраз из чата. Создание файлов зависит от возможностей самого помощника.

Заданием управляет помощник. У MCP нет собственного расписания или фоновой очереди, которая продолжает сбор после закрытия чата. Кэш и история пакетного сбора относятся к команде positions run; обычные MCP-вызовы сами их не создают.

Первое подключение

Этот раздел нужен один раз. Если XMLRiver уже подключён, попросите помощника проверить баланс и начинайте работу.

1. Зарегистрируйтесь на xmlriver.com и пополните баланс.
2. Возьмите в кабинете свой user и key. Они есть в примере адреса API-запроса: user=... и key=....
3. Выберите один способ запуска ниже.
4. Добавьте сервер и ключи в настройки помощника.

Самый простой способ для нового пользователя — запуск через uvx. Установите uv один раз. При первом подключении uvx сам скачает пакет и его зависимости. Отдельно устанавливать пакет через pip или uv tool install не требуется.

Если пакет уже установлен через pip или uv tool install, используйте команду xmlriver-mcp из установленного окружения. Повторно устанавливать пакет или добавлять uv ради MCP не нужно. В примерах настроек замените command на полный путь к xmlriver-mcp (в Windows — xmlriver-mcp.exe), а args на []. Вариант с pip требует Python 3.11 или новее.

Где хранить ключи

PowerShell для настройки ключей не нужен. Проще всего один раз записать их в файл настроек MCP: в блок env для Claude/Cursor или mcp_servers.xmlriver.env для Codex. Готовые примеры приведены ниже. Клиент передаст ключи серверу при запуске.

Также сервер принимает XMLRIVER_USER и XMLRIVER_KEY из окружения процесса. Этот вариант подходит для терминала, скриптов и автоматических заданий.

Файл .env сам пакет автоматически не читает. Он сработает, только если ваш клиент или запускной скрипт загружает его и передаёт значения серверу. Просто положить .env рядом с проектом недостаточно.

Ключи не отправляйте в чат и не выкладывайте в GitHub. Файл настроек с ключами храните локально; если он лежит в Git-проекте, исключите его из коммитов.

Подключение к Claude и Cursor

MCP — способ подключить внешний инструмент к AI-помощнику. После подключения помощник сможет сам запрашивать данные XMLRiver.

Откройте файл настроек MCP:

• Claude Desktop: Settings → Developer → Edit Config.
• Claude Code: файл .mcp.json в папке вашего проекта.
• Cursor: файл .cursor/mcp.json в папке проекта.

Добавьте запись ниже. Замените ВАШ_USER и ВАШ_KEY своими значениями из XMLRiver. Если в файле уже есть другие серверы, добавьте только блок xmlriver внутрь существующего mcpServers.

{
  "mcpServers": {
    "xmlriver": {
      "command": "uvx",
      "args": ["--from", "xmlriver-mcp-toolkit==0.1.1", "xmlriver-mcp"],
      "env": {
        "XMLRIVER_USER": "ВАШ_USER",
        "XMLRIVER_KEY": "ВАШ_KEY"
      }
    }
  }
}

Сохраните файл и перезапустите помощника. При первом запуске uvx скачает пакет. Если помощник не находит uvx, укажите полный путь к нему в поле command. В Windows узнать путь можно командой where.exe uvx.

Подключение к Codex

Добавьте в файл ~/.codex/config.toml (в Windows — %USERPROFILE%\.codex\config.toml):

[mcp_servers.xmlriver]
command = "uvx"
args = ["--from", "xmlriver-mcp-toolkit==0.1.1", "xmlriver-mcp"]

[mcp_servers.xmlriver.env]
XMLRIVER_USER = "ВАШ_USER"
XMLRIVER_KEY = "ВАШ_KEY"

Замените значения ключей, сохраните файл и начните новую сессию Codex.

Что попросить у помощника

Начните с простого:

Проверь баланс XMLRiver.

Затем попробуйте SEO-задачи:

Через Wordstat подбери 50 расширений запроса «кофемашина для дома» по Москве. Оставь запросы с частотностью от 100. Похожие запросы не добавляй.

Посмотри динамику спроса по запросу «купить велосипед» с 01.01.2026 по 31.03.2026.

Собери первые три страницы выдачи Google по запросу «ремонт кофемашин» в Москве для мобильных устройств. Покажи ссылки и позиции example.org.

Покажи выдачу Яндекса по запросу «доставка цветов» в Санкт-Петербурге. Регион 2, устройство — компьютер, одна страница.

Если помощник просит выбрать инструмент, используются четыре названия: get_balance, wordstat_top, wordstat_history, serp.

Дополнительно: запуск из терминала без помощника

Для обычной работы через чат этот раздел можно пропустить. Здесь описан ручной запуск большого сбора с кэшем, историей и обновлением таблицы. Помощник с доступом к терминалу может выполнить эти шаги за вас.

1. Проверьте, доступна ли команда:

xmlriver --help

Если она работает, переходите к ключам. Если пакет ещё не установлен как отдельная команда, установите его один раз:

uv tool install xmlriver-mcp-toolkit==0.1.1

2. Передайте ключи команде. Если они уже есть в окружении терминала, этот шаг пропустите. Ключи из настроек MCP относятся к серверу, запущенному помощником, и не обязательно доступны отдельному терминалу.

Один из способов задать их для текущего окна Windows PowerShell:

$env:XMLRIVER_USER = "ВАШ_USER"
$env:XMLRIVER_KEY = "ВАШ_KEY"

В macOS или Linux:

export XMLRIVER_USER="ВАШ_USER"
export XMLRIVER_KEY="ВАШ_KEY"

3. Подготовьте CSV с запросами. Например, keywords.csv:

phrase
кофемашина для дома
купить кофемашину
ремонт кофемашин

4. Рядом создайте файл positions.yaml:

target_domain: example.org
include_subdomains: true
csv: keywords.csv
column: phrase
depth: 50
max_attempts: 100
engines:
  - name: yandex
    region: 213
    device: mobile
  - name: google
    region: 1011969
    device: mobile

Замените example.org своим доменом. Здесь заданы Москва, мобильная выдача и пять страниц на запрос. include_subdomains: true включает поддомены сайта. max_attempts: 100 ограничивает общее число HTTP-попыток, включая повторы после ошибок.

5. Посмотрите объём задания без списаний:

xmlriver positions run --config positions.yaml --dry-run

6. Запустите сбор:

xmlriver positions run --config positions.yaml

Рядом с конфигурацией появится папка xmlriver-data с результатами и историей. Команда напечатает run_id — идентификатор прогона. Чтобы добавить позиции в CSV:

xmlriver positions update-csv --config positions.yaml --run ВАШ_RUN_ID

Исходные колонки и порядок строк сохраняются. Перед обновлением создаётся резервная копия. Для Яндекса и Google записываются отдельные даты съёма.

Дополнительно: пакетная проверка по регионам

В примере конфигурации есть блок regions. Добавьте нужные города, их ID в Яндексе и Google, а в expected_hosts — домены, которые ожидаете увидеть в выдаче.

xmlriver regions validate --config positions.yaml
xmlriver regions run --config positions.yaml --dry-run
xmlriver regions run --config positions.yaml

Google-регионы сверяются со справочником XMLRiver. Проверка Яндекс-региона делает запрос «погода» и ищет признаки города в выдаче: это подсказка для проверки настройки, а не гарантия. Чтобы заново скачать справочник Google, добавьте к regions validate параметр --refresh.

Расходы и особенности данных

• Запросы оплачиваются с вашего баланса XMLRiver. Сам пакет бесплатный.
• Одна страница выдачи — отдельный запрос к сервису. Больше страниц, фраз и регионов — больше запросов.
• Можно запросить от 1 до 10 страниц. Страница может содержать меньше 10 органических результатов, поэтому пять страниц не гарантируют 50 ссылок.
• Позиция — номер органического результата в полученной последовательности. Рекламные блоки в этот номер не входят.
• Повтор после сетевой ошибки тоже может привести к списанию. Счётчик попыток и оценка расходов не заменяют данные кабинета XMLRiver.
• Результаты массового съёма хранятся в кэше 24 часа. Повторный запуск с теми же параметрами использует их. Для нового съёма добавьте --refresh.
• --dry-run не обращается к API и ничего не записывает. Команды проверки баланса и регионов обращаются к сети.
• В Wordstat по умолчанию используются Москва и все устройства; в SERP — Москва и мобильные устройства.

Если в результате указана неизвестная стоимость (null), тариф не задан или не получен. Это не означает бесплатный сбор.

Если что-то не работает

• Не удаётся запустить сервер: проверьте установку uv и путь к uvx, затем перезапустите помощника.
• Ошибка авторизации: проверьте XMLRIVER_USER и XMLRIVER_KEY в настройках.
• Недостаточно средств: пополните баланс XMLRiver.
• Неверный регион: у Яндекса и Google разные справочники ID. Справочник Google.
• Не принимается период Wordstat: даты должны быть в формате дд.мм.гггг; ограничения на длительность периода описаны в документации XMLRiver.

Сообщить об ошибке можно в Issues. Укажите команду и текст ошибки, удалив ключи и другие личные данные.

Лицензия MIT. Для разработчиков: CONTRIBUTING.md.