wb-mcp-server

<div align="center">

![Русский](https://img.shields.io/badge/%D0%A0%D1%83%D1%81%D1%81%D0%BA%D0%B8%D0%B9-0A66C2?style=for-the-badge)
[![English](https://img.shields.io/badge/English-8B949E?style=for-the-badge)](README.en.md)
[![中文](https://img.shields.io/badge/%E4%B8%AD%E6%96%87-8B949E?style=for-the-badge)](README.zh.md)

</div>

# WB MCP Server

[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
[![MCP tools](https://img.shields.io/badge/MCP%20tools-202-orange.svg)](docs/tools.md)
[![PyPI](https://img.shields.io/pypi/v/wb-mcp-server.svg)](https://pypi.org/project/wb-mcp-server/)
[![Transport](https://img.shields.io/badge/transport-stdio%20%7C%20SSE-lightgrey.svg)](#как-это-устроено)

**Управляйте магазинами Wildberries из чата с ИИ-ассистентом.**
202 инструмента Seller API — карточки, цены, реклама, поставки, отзывы, финансы, аналитика —
доступны Claude, Cursor, Copilot, Gemini CLI и любому другому MCP-клиенту.
Для продавцов WB, у которых один или несколько кабинетов и нет желания кликать в личном
кабинете то, что можно спросить словами.

Торгуете ещё и на Ozon? Есть [такой же сервер для Ozon](https://github.com/DeviceIngineering/ozon-mcp-server).

Сервер в ежедневной работе больше пяти месяцев, на порядка двадцати кабинетах WB,
202 инструмента. Это личный рабочий инструмент автора, и обновляется он по мере
собственной необходимости — [как именно](#обновления-и-поддержка).

```
Ты: Какие мои карточки заблокированы и почему?
Ты: Покажи ДРР по всем кампаниям за неделю и выключи те, где он выше 15%.
Ты: На каких складах коэффициент приёмки сейчас 0 или 1?
Ты: Ответь на все новые отзывы с оценкой 5 благодарностью.
```

![Дашборд WB MCP Server](docs/img/dashboard.png)

---

## Что умеет

202 инструмента, сгруппированные по разделам Wildberries Seller API.
Полный нумерованный список с описанием каждого — в **[docs/tools.md](docs/tools.md)**.

| Раздел | Кол-во | Что закрывает |
|---|---:|---|
| Карточки товаров | 26 | список и детали карточек, создание и обновление, SEO, характеристики, баркоды, медиа, теги, корзина, **карточки с ошибками и блокировками** |
| Цены и скидки | 7 | текущие цены, установка цен и скидок, карантин, WB Клуб, B2B, статус загрузки |
| Акции и автоакции | 7 | календарь промо, автоакции, аудит «куда WB уже добавил товары», вход и выход из акции |
| Реклама | 22 | список и создание кампаний, статистика и ДРР, ставки и рекомендации, кластеры и минус-фразы, баланс и пополнение |
| Аналитика | 25 | воронка продаж v3, история по дням, остатки, антифрод, платная приёмка, штрафы за замеры, доля бренда, продажи по регионам, поисковые запросы |
| Статистика | 3 | продажи, заказы, остатки (statistics-api) |
| Заказы FBS | 29 | новые и все сборочные задания, статусы, отмена, стикеры, поставки, короба, пропуска, маркировка КИЗ |
| Заказы DBS | 10 | доставка силами продавца: заказы, статусы, действия, даты доставки, метаданные |
| Самовывоз (click & collect) | 9 | заказы самовывоза, подтверждение личности покупателя, действия и метаданные |
| Поставки FBW | 6 | поставки на склады WB, товары в поставке, склады, **коэффициенты приёмки на 14 дней** |
| Склады и остатки | 8 | склады продавца, обновление и получение остатков |
| Финансы | 7 | отчёты о реализации, детализация, эквайринг, баланс, данные продавца |
| Тарифы и хранение | 6 | короба, паллеты, возвраты, комиссии, транзит FBW, платное хранение |
| Отзывы и вопросы | 18 | отзывы и вопросы, ответы, счётчики за период, архив, закреплённые отзывы, рейтинг продавца |
| Возвраты | 3 | заявки на возврат, ответ на заявку, отчёт по возвратам |
| Чаты с покупателями | 4 | чаты, события, отправка сообщений, скачивание вложений |
| Документы | 4 | категории документов, список, скачивание по одному и пакетом |
| Пользователи | 2 | сотрудники и приглашения |
| WB Джем | 1 | статус подписки на Джем |
| Магазины | 1 | список подключённых магазинов |
| Диагностика | 4 | самодиагностика, разбор токена, деградации инструментов, новости API WB |

Три вещи, которых обычно нет у похожих серверов:

- **Мульти-магазин.** Каждый вызов принимает `shop_id`, поэтому два кабинета WB живут
  в одном диалоге. Если магазин один — `shop_id` можно не указывать.
- **Диагностика WB API.** Сервер сам пингует хосты WB, делает лёгкие пробные запросы
  по каждой категории, разбирает срок действия и права токена и подсвечивает
  «деградации»: инструмент раньше работал, а теперь стабильно падает — верный признак,
  что WB изменил API.
- **Шифрование токенов.** Токены WB лежат зашифрованными (Fernet), а не в конфиге клиента.

## Быстрый старт

### Вариант 1: одна команда, без Docker

Сервер работает по stdio — так его подключают Claude Desktop, Cursor, VS Code и
другие MCP-клиенты. Ничего собирать не нужно:

```bash
uvx wb-mcp-server
```

Или через pip:

```bash
pip install wb-mcp-server
wb-mcp
```

Конфигурация клиента (например, `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "wildberries": {
      "command": "uvx",
      "args": ["wb-mcp-server"],
      "env": {
        "WB_API_TOKEN": "ваш токен Wildberries API",
        "DATA_DIR": "~/.wb-mcp"
      }
    }
  }
}
```

`DATA_DIR` укажите на любой доступный для записи каталог — там хранятся магазины,
ключи и статистика. По умолчанию используется `/data` (путь для Docker).

### Вариант 2: Docker с веб-интерфейсом

Нужен, если хотите дашборд, диагностику WB API и удобное добавление магазинов
через браузер. Понадобится Docker (Docker Desktop или OrbStack) и токен
Wildberries Seller API.

```bash
git clone https://github.com/DeviceIngineering/wb-mcp-server.git
cd wb-mcp-server
cp .env.example .env          # для локального запуска можно оставить как есть
docker compose up -d --build
```

Проверка:

```bash
curl -s http://localhost:8001/api/health
# {"status":"ok","auth_enabled":false,"health_check_interval_min":30,...}
```

Что открылось:

| Адрес | Что это |
|---|---|
| <http://localhost:8001> | дашборд: вызовы инструментов, ошибки, время ответа |
| <http://localhost:8001/shops> | магазины: добавить кабинет WB, проверить токен |
| <http://localhost:8001/diagnostics> | диагностика: токены, ping хостов WB, пробы, история |
| <http://localhost:8001/api/health> | JSON-сводка для внешнего мониторинга |
| `http://localhost:8001/sse` | **MCP-эндпоинт**, его вы даёте клиенту |

Дальше:

1. Откройте <http://localhost:8001/shops> → **Добавить магазин** → вставьте токен WB → **Проверить**.
   Токен берётся в портале продавца: **Настройки → Доступ к API → Создать токен**
   (срок жизни 180 дней, остаток виден на странице диагностики).
2. Подключите MCP-клиент — см. следующий раздел.
3. Спросите ассистента: «покажи список моих магазинов на Wildberries» — должен сработать
   инструмент `wb_list_shops`.

Разбор команды запуска:

| Флаг | Зачем |
|---|---|
| `up` | поднять сервис, описанный в `docker-compose.yml` |
| `-d` | в фоне, не занимая терминал |
| `--build` | собрать образ из `Dockerfile` — нужно при первом запуске и после обновления кода |

Остановить: `docker compose down` (данные останутся в томе `wb_data`).
Логи: `docker compose logs -f`.

<details>
<summary>Запуск без Docker</summary>

```bash
git clone https://github.com/DeviceIngineering/wb-mcp-server.git
cd wb-mcp-server
python3 -m venv .venv && source .venv/bin/activate
pip install .
DATA_DIR=./data PORT=8001 python -m wb_mcp.app
```

`DATA_DIR` указывать обязательно: по умолчанию сервер пишет в `/data` — путь внутри контейнера.
</details>

## Установка в клиенты

Сервер отдаёт MCP по **SSE**: `GET /sse` — поток событий, `POST /messages` — сообщения клиента.
Поддержка SSE у клиентов разная, поэтому под каждый есть отдельная инструкция —
с путями к конфигу на macOS, Linux и Windows, готовым JSON и вариантами с токеном и без.

| Клиент | SSE напрямую | Инструкция |
|---|---|---|
| Claude Code | да | [docs/install-claude-code.md](docs/install-claude-code.md) |
| Claude Desktop | нет → мост `mcp-remote` или локальный stdio | [docs/install-claude-desktop.md](docs/install-claude-desktop.md) |
| Cursor | да | [docs/install-cursor.md](docs/install-cursor.md) |
| Windsurf | да | [docs/install-windsurf.md](docs/install-windsurf.md) |
| VS Code (GitHub Copilot) | да | [docs/install-vscode-copilot.md](docs/install-vscode-copilot.md) |
| Cline | да | [docs/install-cline.md](docs/install-cline.md) |
| Continue.dev | да | [docs/install-continue.md](docs/install-continue.md) |
| Zed | по URL; поддержка SSE официально не заявлена | [docs/install-zed.md](docs/install-zed.md) |
| JetBrains AI Assistant | да (SSE как legacy) | [docs/install-jetbrains.md](docs/install-jetbrains.md) |
| Gemini CLI | да | [docs/install-gemini-cli.md](docs/install-gemini-cli.md) |
| Codex CLI | нет → мост `mcp-remote` | [docs/install-codex.md](docs/install-codex.md) |

Общий обзор и таблица совместимости — [docs/README.md](docs/README.md).

Где у клиента есть команда, настраивающая подключение самостоятельно, инструкция начинается
с неё, а правка JSON идёт вторым способом. Самый короткий вариант — Claude Code:

```bash
claude mcp add --transport sse wildberries http://localhost:8001/sse
claude mcp list      # ожидается: wildberries ... ✔ Connected
```

## Мульти-магазин и безопасность

**Несколько кабинетов.** Магазины добавляются на `/shops`, каждый получает свой `shop_id`.
Инструмент `wb_list_shops` возвращает список; 200 из 202 инструментов принимают `shop_id`
первым параметром (исключения — `wb_list_shops` и `wb_degradations`).
Если магазин один, параметр можно опустить: сервер подставит единственный доступный.

Смысл не в том, чтобы «уметь два аккаунта», а в том, что **стратегия пишется один раз
и раскатывается на все кабинеты**: правило по ценам, шаблон ответов на отзывы, потолок
ставки в рекламе применяются ко всем магазинам в одном диалоге — без переключения
аккаунтов и без раскладывания ключей по конфигам разных клиентов.
**Сколько кабинетов можно подключить.** Ограничения в коде нет: `shops.json`