XMLRiver MCP Toolkit

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

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

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

Что умеет

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

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

Проверь позиции 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.