XMLRiver MCP Toolkit

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

Подключите инструмент к Claude, Codex или Cursor и ставьте задачи обычным языком. Помощник обратится к XMLRiver и вернёт данные: запросы, частотности, позиции и ссылки. Для массового съёма позиций есть отдельные команды с сохранением результатов в файлы.

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

Что умеет

Что нужно для начала

1. Зарегистрируйтесь на xmlriver.com и пополните баланс.
2. Возьмите в кабинете XMLRiver свой user и key. Они есть в примере адреса API-запроса: user=... и key=....
3. Установите uv — небольшую программу, которая скачает и запустит этот инструмент.
4. Подключите сервер в своём AI-помощнике по инструкции ниже.

Ключи XMLRiver — личные. Не отправляйте их в чат и не выкладывайте в GitHub.

Подключение к 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.0", "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.0", "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. Установите пакет:

uv tool install xmlriver-mcp-toolkit==0.1.0

2. Задайте ключи для текущего окна терминала. В 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.