wb-mcp
# wb-mcp
Подключает кабинет Wildberries к вашему ИИ-ассистенту (Cursor, Claude, Codex, Gemini, VS Code).
Ассистент работает с настоящими заказами, остатками, продажами, отзывами и ценами из WB — а не
придумывает их.
[](https://www.npmjs.com/package/wildberries-seller-mcp)
[](https://nodejs.org/)
[](./LICENSE)
## Зачем это нужно
- **Ассистент сам знает, что спросить у Wildberries.** Не нужно объяснять ему команды и пути
к методам API — он находит нужное по обычной просьбе: «сколько заказов вчера», «почему упали
продажи», «какие товары заканчиваются».
- **Работает с реальными данными кабинета:** заказы, продажи, остатки, товары и цены, отзывы
и вопросы, реклама, поставки, финансы, документы.
- **Может не только читать, но и менять.** Цены, остатки, ответы на отзывы, ставки в рекламе —
но каждое изменение ассистент сначала показывает вам, а делает только после подтверждения.
- **Всё на вашем компьютере.** Сервер запускается локально, ваш токен хранится в зашифрованном
виде и не отправляется никуда, кроме самого Wildberries. Платить за хостинг не нужно.
- **Не ломает ваш кабинет.** Учитывает лимиты Wildberries, повторяет запрос, если WB попросил
подождать, и сохраняет большие отчёты в файл, чтобы они не занимали весь чат.
- **Установка занимает пару минут**, а каталог методов обновляется одной командой, когда WB меняет API.
## Установка
### 1. Получите токен Wildberries
Кабинет продавца → **Настройки → Интеграции по API → Создать токен**.
Для начала достаточно режима **«Только чтение»** и минимума категорий — так ассистент не сможет
ничего испортить, даже если ошибается.
### 2. Установите сервер
Самый простой путь — универсальный установщик. Он найдёт ваши клиенты, пропишет их конфиги,
скачает каталог методов и сохранит токен в зашифрованном виде:
```bash
node install.mjs --client all --token <ваш_токен>
```
Если репозиторий не скачан:
```bash
npx -y -p wildberries-seller-mcp wb-mcp-install --client all --token <ваш_токен>
```
### Или установите в конкретный клиент
Все установочные файлы лежат на странице
[Releases → catalog](https://github.com/Gregory-mcbit/wildberries-mcp/releases/tag/catalog).
| Клиент | Что сделать |
|---|---|
| **Claude Desktop** | Скачайте [wb-mcp.mcpb](https://github.com/Gregory-mcbit/wildberries-mcp/releases/download/catalog/wb-mcp.mcpb) и откройте файл двойным кликом. Claude сам предложит окно, куда нужно вставить токен. |
| **Cursor** | [Установить в Cursor](https://cursor.com/install-mcp?name=wb&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIi1wIiwiZ2l0aHViOkdyZWdvcnktbWNiaXQvd2lsZGJlcnJpZXMtbWNwIiwid2ItbWNwIl0sImVudiI6eyJXQl9BVVRPX1NZTkMiOiIxIiwiV0JfQVBJX1RPS0VOIjoiUEFTVEVfWU9VUl9XQl9BUElfVE9LRU4ifX0%3D) — откроется окно установки в Cursor. После этого откройте конфигурацию MCP и замените текст `PASTE_YOUR_WB_API_TOKEN` на свой токен. Это единственное место, где нужно что-то вписать. |
| **VS Code** | [Установить в VS Code](vscode:mcp/install?%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22-p%22%2C%22github%3AGregory-mcbit%2Fwildberries-mcp%22%2C%22wb-mcp%22%5D%2C%22env%22%3A%7B%22WB_AUTO_SYNC%22%3A%221%22%2C%22WB_API_TOKEN%22%3A%22PASTE_YOUR_WB_API_TOKEN%22%7D%7D) — откроется окно подтверждения установки. Если окно не открылось, запустите универсальный установщик выше, результат будет тот же. |
| **Claude Code** | `claude mcp add wb --env WB_API_TOKEN=<токен> -- node <путь>/server.mjs` |
| **Codex CLI** | `codex mcp add wb --env WB_API_TOKEN=<токен> -- node <путь>/server.mjs` |
| **Gemini CLI** | `gemini mcp add wb --env WB_API_TOKEN=<токен> -- node <путь>/server.mjs` |
| **Без установки** | Скачайте [wb-mcp-portable.zip](https://github.com/Gregory-mcbit/wildberries-mcp/releases/download/catalog/wb-mcp-portable.zip), распакуйте и запустите `install.cmd` (Windows) или `install.sh` (macOS/Linux). |
### Можно поручить установку ассистенту
Не хотите ставить руками — дайте ассистенту ссылку на репозиторий и попросите:
> «Подключи wb-mcp из https://github.com/Gregory-mcbit/wildberries-mcp по инструкции AGENT-INSTALL.md»
Ассистент откроет [AGENT-INSTALL.md](https://github.com/Gregory-mcbit/wildberries-mcp/blob/main/AGENT-INSTALL.md),
скачает репозиторий, запустит установщик, сохранит токен в зашифрованном виде и проверит подключение
через `doctor`. Токен он спросит у вас.
### 3. Перезапустите ассистента и проверьте
Напишите ассистенту: **«покажи разделы WB API»**. Если всё подключено, он покажет список
разделов кабинета.
Если что-то не работает, выполните проверку — она подскажет, в чём дело:
```bash
node ~/.wb-mcp/app/doctor.mjs
```
## Что можно попросить у ассистента
- «Сколько заказов и продаж было за вчера и позавчера?»
- «Почему упали продажи за неделю?»
- «Какие товары скоро закончатся на складах?»
- «Покажи неотвеченные отзывы и предложи ответы»
- «Измени цену на этот товар на 5% ниже» — ассистент покажет, что именно изменит.
- «Сделай недельный отчёт по магазину»
В комплекте есть готовые сценарии на такие задачи: полный разбор роста продаж, разбор падения
заказов, проверка остатков, работа с отзывами и недельный отчёт. В Cursor и Claude они доступны
как команды вида `/sales-accelerator`.
### Несколько магазинов
Установите все токены сразу — каждый сохранится в отдельный **зашифрованный** файл, а в конфиг
попадёт только список путей `WB_TOKEN_FILES`:
```bash
node install.mjs --client all --accounts '{"основной":"<токен1>","второй":"<токен2>"}'
```
Ассистент увидит все аккаунты в `wb_sections` и `wb_token_info`, а в запросе укажет `account`.
Файлы аккаунтов получают уникальные имена (имя + хэш), поэтому даже похожие названия не смешиваются.
## Обновление
```bash
node ~/.wb-mcp/app/sync.mjs # заново скачать свежие описания методов Wildberries
```
Или попросите ассистента: «обнови каталог Wildberries».
## Безопасность
- Токен хранится в зашифрованном файле (AES-256-GCM); в настройках клиента — только путь к нему.
Ключ шифрования защищён системным keychain: **DPAPI** на Windows, **Keychain** на macOS,
**libsecret** на Linux.
- Запросы уходят только на адреса Wildberries и **только по HTTPS** — `http://` блокируется.
- Изменяющие запросы требуют подтверждения: сервер сам останавливает запись, пока ассистент не
передаст одноразовый код (действует 5 минут), а если клиент умеет — запрашивает согласие человека
через `elicitation`; ответ модели через `sampling` разбирается строго (любое «не» = отказ).
- Режим «только чтение» (`WB_READONLY=1`) блокирует запись и через обычный вызов, и через сырой
запрос `wb_request`.
- Чтение и изменение разделены: ассистент не может незаметно что-то поменять. Если токен создан
в режиме «Только чтение», изменить данные через него невозможно вообще.
- Логи не содержат ваших данных: ни тел запросов, ни ответов.
**Честно про подтверждение:** гарантировать согласие человека может только клиент, который умеет
спрашивать пользователя (`elicitation`). Если клиент умеет только `sampling` — это запрос к модели,
и сервер страхуется строгим разбором ответа. Если клиент не умеет ни того, ни другого, остаётся
двухэтапное подтверждение агентом с одноразовым кодом, и сервер явно помечает это в ответе
(`humanApproval: "unavailable"`). Для максимально строгого режима задайте **`WB_CONFIRM_HUMAN=require`**:
тогда запись разрешена только при подтверждении человеком через `elicitation`, иначе сервер отказывает.
**Честно про хранение токена:** ключ шифрования хранится в системном keychain — DPAPI на Windows,
Keychain на macOS, libsecret на Linux (если сервис секретов недоступен, ключ останется файлом рядом
с данными). От вредоносной программы, работающей под вашим пользователем, ни одна из схем всё равно
не спасает. Не передавайте токен аргументом `--token` — он останется в истории команд; вместо этого
задайте переменную окружения `WB_API_TOKEN` или установите через интерактивную установку.
## Лицензия
MIT — см. [LICENSE](./LICENSE). Английская версия — [README.en.md](./README.en.md).
TDQS
Scored across 8 tools
The core split between wb_get (read-only) and wb_call (mutating) is explicit and reinforced in both descriptions, and search/describe/sections serve clearly different discovery stages. The only fuzzy boundary is wb_request, which as a raw HTTP escape hatch can overlap with wb_get/wb_call for already-catalogued methods, though its 'new method not in catalog' framing mitigates this.
All tools uniformly use the wb_ prefix in lowercase snake_case, making the set instantly readable as one family. Minor deviation: most names are single verbs (search, describe, get, call, refresh) but wb_sections and wb_token_info are noun/noun+verb forms, so the pattern is not a pure verb_noun scheme.
Eight tools is tightly scoped for a catalog-and-invoke proxy: discovery (sections, search, describe), execution (get, call), auth diagnostics (token_info), and maintenance (refresh, request). Each tool has a distinct role and none feels redundant.
The search → describe → get/call workflow covers the full read and write lifecycle, with token diagnostics, catalog refresh, and a raw-request fallback for uncatalogued endpoints. Minor gaps: no way to enumerate all methods in a section (only counts), and no batch/pagination helper for high-volume reads.