# XMLRiver MCP Toolkit

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

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

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

<!-- mcp-name: io.github.dietbear13/xmlriver-mcp-toolkit -->

## Что умеет

| Задача | Что получите |
|---|---|
| Подобрать запросы в 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](https://xmlriver.com/) и пополните баланс.
2. Возьмите в кабинете свой **user** и **key**. Они есть в примере адреса API-запроса: `user=...` и `key=...`.
3. Выберите один способ запуска ниже.
4. Добавьте сервер и ключи в настройки помощника.

**Самый простой способ для нового пользователя — запуск через `uvx`.** Установите [uv](https://docs.astral.sh/uv/getting-started/installation/) один раз. При первом подключении `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`.

```json
{
  "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`):

```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. Проверьте, доступна ли команда:**

```sh
xmlriver --help
```

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

```sh
uv tool install xmlriver-mcp-toolkit==0.1.1
```

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

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

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

В macOS или Linux:

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

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

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

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

```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. Посмотрите объём задания без списаний:**

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

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

```sh
xmlriver positions run --config positions.yaml
```

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

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

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

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

В [примере конфигурации](examples/positions.yaml) есть блок `regions`. Добавьте нужные города,
их ID в Яндексе и Google, а в `expected_hosts` — домены, которые ожидаете увидеть в выдаче.

```sh
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](https://xmlriver.com/files/geo.csv).
- **Не принимается период Wordstat:** даты должны быть в формате `дд.мм.гггг`; ограничения на длительность периода описаны в [документации XMLRiver](https://xmlriver.com/apiwordstatnew/apiwn-about/).

Сообщить об ошибке можно в [Issues](https://github.com/dietbear13/xmlriver_mcp/issues). Укажите команду и текст ошибки, удалив ключи и другие личные данные.

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