Back to Browse

Xmlriver MCP Server

Developer ToolsUse Caution4.5MCP RegistryLocal
Free

Server data from the Official MCP Registry

Google/Yandex organic results, Wordstat keywords and demand history using your XMLRiver account.

About

Google/Yandex organic results, Wordstat keywords and demand history using your XMLRiver account.

Security Report

4.5
Use Caution4.5High Risk

Valid MCP server (1 strong, 0 medium validity signals). 10 known CVEs in dependencies (0 critical, 1 high severity) Package registry verified. Imported from the Official MCP Registry.

7 files analyzed · 11 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

file_system

Check that this permission is expected for this type of plugin.

HTTP Network Access

Connects to external APIs or services over the internet.

env_vars

Check that this permission is expected for this type of plugin.

What You'll Need

Set these up before or after installing:

XMLRiver user IDRequired

Environment variable: XMLRIVER_USER

XMLRiver API keyRequired

Environment variable: XMLRIVER_KEY

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "xmlriver-mcp-toolkit": {
      "command": "uvx",
      "args": [
        "xmlriver-mcp-toolkit==0.2.0"
      ],
      "env": {
        "XMLRIVER_KEY": "your-xmlriver-key-here",
        "XMLRIVER_USER": "your-xmlriver-user-here"
      }
    }
  }
}

Some servers take additional arguments. See the repository for details.

Documentation

View on GitHub

From the project's GitHub README.

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, истории спроса и поисковой выдачи. Для списка есть инструмент batch: он принимает до 100 фраз за один вызов и обрабатывает их параллельно, до 9 запросов одновременно. Помощник передаёт список и общие настройки, затем оформляет результаты.

Через batch собери Wordstat по фразам «кофемашина», «кофеварка», «кофе в зёрнах». Регион Москва, до 50 расширений каждой фразы, частотность от 100. Используй до 9 параллельных запросов и не больше 30 HTTP-попыток. Покажи общий список.

Для выдачи используется операция serp, для расширений — wordstat_top, для динамики спроса — wordstat_history. Все фразы внутри одного пакета используют одинаковые параметры. Результаты возвращаются в порядке исходного списка; у каждой фразы есть свой статус и число HTTP-попыток.

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

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

В таком режиме помощник сам готовит задание и запускает команду. Если клиент умеет только вызывать MCP, используйте batch прямо из чата: сервер сам сохраняет его результаты, доступ помощника к терминалу для этого не нужен.

Заданием управляет помощник. У MCP нет собственного расписания или фоновой очереди, которая продолжает сбор после закрытия чата. Команды positions run, regions run, batch и MCP-инструмент batch сохраняют результаты на диск по мере получения. При повторе задания используются сохранённые фразы и страницы. Одиночные MCP-вызовы serp, wordstat_top и wordstat_history возвращают данные в чат; для сохранения используйте batch, в том числе со списком из одной фразы.

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

Этот раздел нужен один раз. Если 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.2.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.2.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, batch.

Скорость и параллельный сбор

По умолчанию сервер и пакетные команды работают с 9 одновременными запросами. XMLRiver указывает 10 потоков; один оставлен в запасе. Это лимит одновременной обработки, а не обещание 9 готовых ответов в секунду. Отдельно пакет ограничивает начало запросов: не больше 9 за скользящую секунду. Фактическая скорость зависит от сервиса.

Если свободных каналов не хватает, пакет снижает параллельность и делает общую паузу для запросов этого клиента. После 20 успешных ответов поднимает её на один, максимум до заданного значения. При блокировке учитывает Retry-After и указанное сервисом время ожидания. Если время не указано для ошибки 115 или HTTP 429, пауза составляет 10 минут. Длительный сбор может завершиться по лимиту времени раньше окончания паузы; полученные результаты сохраняются в пакетных командах.

Каждый запрос повторяется не больше трёх раз при временных ошибках. Ошибки ключа, баланса и доступа по IP останавливают дальнейшую отправку в пакетном задании. Уже отправленные запросы могут завершиться. Повторы входят в max_attempts.

В MCP-настройках можно уменьшить предел через XMLRIVER_CONCURRENCY, например до 3. Частота старта регулируется отдельно через XMLRIVER_RATE_MAX и XMLRIVER_RATE_WINDOW (по умолчанию 9 и 1 секунда). В YAML для позиций и регионов используются concurrency, rate_max и rate_window. Для одного запуска также можно передать --concurrency 3.

Ограничение действует внутри одного запущенного клиента. Если одновременно запускаете несколько MCP-серверов, команд или сторонних парсеров с одним аккаунтом XMLRiver, распределите доступные потоки между ними. Например, два процесса по 4 запроса оставят запас до лимита сервиса.

Источники: лимит потоков XMLRiver, ошибки и временная блокировка Wordstat.

Что будет, если сбор остановится

Пакетный сбор записывает каждый полученный результат сразу, а не в конце задания. Ответ Wordstat, каждая страница поисковой выдачи и начало каждой HTTP-попытки попадают в журнал с принудительной записью на диск. Ошибки и незавершённые фразы тоже сохраняются. Большие ответы файлового сбора хранятся на диске; в памяти остаются входной список, служебные сведения и текущие запросы.

  • Успешные фразы берутся из кэша при повторном запуске, без нового запроса к XMLRiver.
  • Если по фразе успели получить только часть страниц, сбор продолжится со следующей сохранённой страницы. Это действует в пределах срока кэша и при тех же параметрах.
  • При обычной остановке сохраняется итоговый частичный отчёт. При принудительном завершении процесса уже записанные данные остаются в журнале; отчёт можно восстановить командой ниже.
  • Параметр refresh в MCP или --refresh в команде запускает сбор заново. Для продолжения после сбоя его добавлять не нужно.

Где лежат данные: у команд — в xmlriver-data рядом с файлом задания, либо в папке из --workspace. У MCP-инструмента batch — в .xmlriver/data внутри домашней папки пользователя. Для другой папки добавьте XMLRIVER_WORKSPACE в настройки окружения MCP. Путь к отчёту возвращается в ответе инструмента.

В каждой папке прогона есть journal.jsonl с записями по мере получения, data.jsonl с итоговыми результатами и manifest.json со статусом и счётчиками. Пока сбор идёт, самые свежие данные находятся в журнале. Чтобы восстановить итоговый файл после аварийного завершения:

xmlriver recover --workspace xmlriver-data --run ИДЕНТИФИКАТОР_ПРОГОНА

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

Дополнительно: большой список Wordstat или выдачи

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

{
  "operation": "wordstat_top",
  "queries": ["кофемашина", "кофеварка", "кофе в зёрнах"],
  "parameters": {"regions": 213, "limit": 50, "min_frequency": 100},
  "concurrency": 9,
  "max_attempts": 100
}

Ключи должны быть переданы в окружение команды, как описано ниже.

xmlriver batch --input batch.json --dry-run
xmlriver batch --input batch.json

Команда возвращает краткий итог и пути к файлам, не печатая всю семантику в терминал. Она принимает до 100 000 исходных фраз. Одновременно выполняется только заданное число запросов, а не весь список сразу. По умолчанию на весь запуск отводится час; изменить срок можно через --deadline 7200 (секунды). Для увеличения бюджета измените max_attempts в задании, максимум 10 000 попыток за запуск.

Рядом появится xmlriver-data с результатами прогонов и кэшем успешных фраз. После остановки повторите ту же команду: результаты за последние 24 часа будут взяты из кэша, остальные фразы соберутся заново. Чтобы принудительно обновить все данные, добавьте --refresh. При изменении региона, устройства или других параметров старый кэш не используется.

Для поисковой выдачи замените operation на serp, а параметры задайте, например, так:

{"engine": "yandex", "region": 213, "device": "mobile", "pages": 5, "target_domain": "example.org"}

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

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

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

xmlriver --help

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

uv tool install xmlriver-mcp-toolkit==0.2.0

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
concurrency: 9
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.

Reviews

No reviews yet

Be the first to review this server!