Marketplace Mcp Install

---
name: marketplace-mcp-install
description: "Установить MCP-серверы Wildberries, Ozon, Яндекс Маркета и Авито (marketplaces-mcp-ru) для не-технического продавца в режиме zero-terminal: человек говорит «поставь маркетплейсы MCP», агент берёт код, запускает install.py под нужного клиента (Claude Desktop / Claude Code / Codex / OpenCode), помогает получить и сохранить API-ключи в локальный кабинет, проверяет установку. Используй, когда пользователь хочет подключить свой кабинет селлера к ИИ. Триггеры: «установи маркетплейс MCP», «подключи WB и Ozon», «настрой продавца WB», «настрой Ozon селлера», «поставь wildberries mcp», «подключи яндекс маркет», «подключи авито», «install marketplace mcp», «добавь кабинет озон/вб»."
---

# Установка marketplaces-mcp-ru (WB, Ozon, Яндекс Маркет, Авито) под не-технического продавца

Цель скилла: пользователь сказал «поставь мне WB и Ozon MCP» — и через несколько минут в его ИИ-клиенте появились инструменты для работы с кабинетом селлера, без ручного редактирования JSON и без `pip install`. Зависимости ставит сам `serve.py` при первом запуске (локальный venv).

**Репозиторий:** `https://github.com/ilyautov/marketplaces-mcp-ru` (опубликован, есть Releases).

**Главный путь — «скинул репо → агент поставил»:** пользователь подключает папку с
репозиторием в Cowork (или она уже на машине), агент запускает `install.py` —
тот **копирует приложение в стабильное место** `~/.marketplace-mcp/app` и
указывает конфиг туда. Поэтому подключённую/скачанную папку потом можно
перемещать или удалять — MCP не сломается. Остальные пути (склонируй сам, pip) —
для тех, кто хочет повозиться руками.

Что внутри: MCP-серверы `wb` (Wildberries Seller API), `ozon` (Ozon Seller API), `yandex` (Yandex Market Partner API), `avito` (Avito API для бизнеса), плюс опциональный `ozon-perf` (рекламный кабинет Ozon Performance). Ключи хранятся локально в `~/.marketplace-mcp/cabinets.json` (chmod 600), НЕ в конфиге клиента и НЕ в репозитории.

---

## Шаг 0 — ОПРЕДЕЛИ СРЕДУ (это критично, не пропускай)

От среды зависит, что ты можешь сделать сам, а что — только провести пользователя за руку. Будь честен про границу: НЕ обещай того, что среда физически не может.

### Ты в Claude Code (или другом локальном CLI, где bash = реальная машина пользователя)

Здесь bash выполняется НА машине пользователя. Ты можешь сделать ВСЁ автоматически:
- склонировать/скачать репозиторий,
- запустить `python3 install.py --client claude-code` (или нужного клиента),
- помочь собрать ключи и сохранить кабинет,
- проверить установку `serve.py ... --selfcheck`.

Проверка среды: запусти `pwd && uname -a && whoami`. Если это домашняя папка пользователя на его ОС (macOS/Windows/Linux), а не контейнер — ты локально. Иди по шагам 1→4 сам.

### Ты в Cowork (bash = изолированная Linux-песочница)

КРИТИЧНО. В Cowork твой bash — это отдельный Linux-контейнер. Он:
- НЕ видит конфиг Claude Desktop пользователя,
- НЕ может прописать хостовый MCP-сервер,
- НЕ может запустить `serve.py` на машине пользователя,
- набирать в терминал пользователя запрещено для безопасности.

Поэтому в Cowork ты НЕ ставишь MCP на машину сам. Признак песочницы: `uname -a` показывает Linux-контейнер, домашняя папка вида `/home/...` или `/sessions/...`, имя пользователя не совпадает с реальным. Твои варианты в Cowork (в порядке предпочтения):

1. **Через Claude Code.** Если у пользователя есть Claude Code — это самый чистый путь. Подготовь точные команды (Шаги 1-4) и попроси выполнить их в Claude Code, либо передай задачу туда.
2. **Двойной клик по установщику + computer-use.** Скачай/подготовь файлы репозитория в ПОДКЛЮЧЁННУЮ папку (которую видит и пользователь, и ты). Дальше через computer-use (если доступен и пользователь дал доступ): открой папку в Finder/Проводнике и сделай двойной клик по `install.command` (macOS) / `install.bat` (Windows) / `bash install.sh` (Linux). Установщик откроется в терминале пользователя и сам спросит ключи.
   - ⚠️ **Gatekeeper (macOS).** Если `install.command` был **скачан браузером** (а не скопирован), на нём стоит карантин и двойной клик молча не сработает («неустановленный разработчик»). Тогда: **правый клик → «Открыть» → «Открыть»**, либо один раз сними карантин: `xattr -d com.apple.quarantine install.command`. Скопированный (не скачанный) файл карантина не имеет — клик сработает сразу.
   - В Finder для навигации используй меню **«Переход → Переход к папке»**, а не шорткат Cmd+Shift+G (через computer-use системный лист по шорткату ловится нестабильно).
3. **Проведи по шагам словами.** Если computer-use нет — дай пользователю короткий, точный чеклист: какую папку открыть, по какому файлу кликнуть, что ввести. Не вываливай простыню — по одному шагу.

Не пиши в Cowork «сейчас установлю» и не делай вид, что серверы появились. Скажи прямо: «Я в песочнице и не могу прописать MCP на твою машину напрямую — давай через двойной клик / Claude Code».

---

## Шаг 1 — Получить код на машину пользователя

Локальная разумная папка: `~/marketplace-mcp` (macOS/Linux) или `%USERPROFILE%\marketplace-mcp` (Windows). В Cowork — подключённая папка пользователя.

> ⚠️ **В Cowork НЕ клонируй прямо в подключённую папку.** Хостовое
> FUSE-монтирование не поддерживает file-locking/unlink, и `git clone` падает с
> `unable to unlink '.git/config.lock': Operation not permitted`. Если репо нужно
> склонировать — клонируй в песочницу (`/tmp`) и копируй БЕЗ `.git`:
> `git clone … /tmp/mmru && rm -rf /tmp/mmru/.git && cp -R /tmp/mmru/. <папка>/`.
> Но чаще клонировать не нужно — папку с репо просто подключают (Вариант В).

**Вариант В (главный) — папка уже подключена/лежит на машине.** Перейди в неё,
проверь, что внутри есть `install.py` и `serve.py`, и сразу иди в Шаг 2.
`install.py` сам скопирует приложение в `~/.marketplace-mcp/app`, поэтому никаких
git-операций на подключённой папке делать НЕ надо — это и обходит FUSE-проблему.

**Вариант А — git clone (только локально, НЕ в Cowork-монтирование):**
```bash
cd ~ && git clone https://github.com/ilyautov/marketplaces-mcp-ru && cd marketplaces-mcp-ru
```

**Вариант Б — скачать release-zip (если git нет):**
- Скачать `marketplaces-mcp-ru-v<версия>.zip` из [Releases](https://github.com/ilyautov/marketplaces-mcp-ru/releases), распаковать.
- macOS/Linux: `cd ~ && curl -L <RELEASE_ZIP_URL> -o mm.zip && unzip mm.zip`

Проверка Python (нужен 3.10+):
```bash
python3 --version   # или: py -3 --version  (Windows)
```
Если Python нет — см. Troubleshooting ниже, сначала поставь его.

---

## Шаг 2 — Запустить установку под нужного клиента

`install.py` ничего не ломает: он находит конфиг под ОС, дописывает две (или три) записи серверов БЕЗ секретов, делает бэкап старого конфига. Повторный запуск безопасен — обновляет записи.

Сначала спроси у пользователя, какой у него клиент. Команды (из папки репозитория):

| Клиент | Команда | Что делает |
|---|---|---|
| **Claude Desktop** (по умолчанию) | `python3 install.py --client claude-desktop` | Пишет `claude_desktop_config.json`, бэкапит старый |
| **Claude Code** (CLI) | `python3 install.py --client claude-code` | ПЕЧАТАЕТ готовые `claude mcp add ...` команды — их надо выполнить |
| **Codex** (CLI) | `python3 install.py --client codex` | ПЕЧАТАЕТ `codex mcp add ...` команды |
| **OpenCode** | `python3 install.py --client opencode` | Пишет `~/.config/opencode/opencode.json` |

Важно про CLI-клиенты: для `claude-code` и `codex` install.py НЕ пишет конфиг сам — он печатает команды `* mcp add wildberries -- ... wb` и т.д. Эти строки нужно реально выполнить (в Claude Code ты можешь сделать это сам через bash; для Codex — выполнить напечатанные команды). При этом ключи, переданные флагами (`--wb-token`, `--ozon-client-id`, `--ozon-api-key`, `--yandex-api-key`, `--avito-client-id`, `--avito-client-secret`, `--ozon-perf-*`), install.py СОХРАНЯЕТ в общий кабинет-стор `~/.marketplace-mcp/cabinets.json` и для этих клиентов тоже — можно передать их сразу одной командой, отдельный запуск для сохранения ключей не нужен.

Только посмотреть блок конфига, ничего не меняя:
```bash
python3 install.py --print
```

После установки в Claude Desktop / OpenCode — **перезапусти клиент**. При первом запуске `serve.py` сам создаст venv и поставит зависимости (это занимает несколько секунд, весь вывод идёт в stderr, stdout остаётся чистым для MCP).

---

## Шаг 3 — Ключи API (где взять и как сохранить)

Ключи НИКОГДА не кладутся в репозиторий и в конфиг клиента. Они идут в локальный кабинет `~/.marketplace-mcp/cabinets.json` (chmod 600).

**Где взять:**
- **Wildberries:** seller.wildberries.ru → Настройки → Доступ к API. Создать токен, отметить нужные категории (Контент, Цены, Статистика, Маркетплейс и т.д.). Это один токен.
- **Ozon (Seller):** seller.ozon.ru → Настройки → API-ключи. Нужны `Client-Id` (число) и `Api-Key`.
- **Яндекс Маркет (опционально):** один `Api-Key` из partner.market.yandex.ru → Настройки → Доступ к API. Флаг `--yandex-api-key`.
- **Авито (опционально):** `client_id` + `client_secret` из avito.ru → Для бизнеса → Интеграции → API (OAuth2 client_credentials). Флаги `--avito-client-id` / `--avito-client-secret`.
- **Ozon Performance (реклама, ОПЦИОНАЛЬНО):** отдельные `Client-Id` + `Client-Secret` из РЕКЛАМНОГО кабинета Ozon Performance (OAuth2). Это НЕ те же ключи, что у Seller API. Нужны только если пользователь хочет работать с рекламой. **По умолчанию интерактив их НЕ спрашивает** (чтобы продавец вводил 3 поля, а не 5) — добавь флаг `--with-ads`, только если реклама реально нужна.

**Как сохранить — два пути:**

Путь 1 — интерактивно через install.py (спросит 3 поля: WB-токен + Ozon Client-Id + Api-Key; Enter = пропустить):
```bash
python3 install.py            # 3 поля
python3 install.py --with-ads # + 2 поля Ozon Performance (реклама)
```

Путь 2 — флагами (удобно, если ключи уже есть; ПРАВИЛО: не эхай реальные значения в чат):
```bash
python3 install.py \
  --wb-token <WB_TOKEN> \
  --ozon-client-id <CLIENT_ID> \
  --ozon-api-key <API_KEY>
# опционально реклама:
#   --ozon-perf-client-id <ID> --ozon-perf-client-secret <SECRET>
#   --yandex-api-key <KEY> --avito-client-id <ID> --avito-client-secret <SECRET>
# несколько магазинов: добавь --cabinet shop2 (по умолчанию 'main')
```

Путь 3 — из чата, когда серверы уже подключены, через их инструменты:
- `wb_add_cabinet`, `ozon_add_cabinet` — добавить/обновить кабинет:
  `add_cabinet(name="main", credentials={"client_id":"...","api_key":"..."})`
- `ozon_use_cabinet(name)` — переключить активный кабинет
- `ozon_list_cabinets` — посмотреть кабинеты и активный
- `ozon_remove_cabinet(name)` — удалить

**Безопасность ключей (обязательно):**
- НИКОГДА не печатай секреты обратно в чат, даже частично.
- Если ключ случайно засветился в переписке/логах — сразу предложи перевыпустить его в кабинете селлера (старый отозвать).
- Несколько магазинов → разные `--cabinet` имена, переключение `ozon_use_cabinet`.

---

## Шаг 4 — Проверка

> **Стандарт верификации: после рестарта через сами MCP-инструменты, а НЕ чтением
> конфига.** Конфиг Claude Desktop лежит в защищённой папке, которую агент из
> Cowork прочитать не может (`request_cowork_directory` по ней отдаёт «internal
> session storage»). Поэтому не пытайся верифицировать чтением конфига — проверяй
> живым вызовом инструмента.

**Что установилось** — видно без доступа к конфигу: `~/.marketplace-mcp/last_install.json`
(breadcrumb, который пишет `install.py`): список серверов, путь к `serve.py`,
время. Секретов там нет.

**Селфчек сервера** (считает количество инструментов, ключи не нужны). Приложение
скопировано в каноническую папку, поэтому путь — оттуда:
```bash
python3 ~/.marketplace-mcp/app/serve.py ozon --selfcheck   # -> "OK: ozon ready, N tools."
python3 ~/.marketplace-mcp/app/serve.py wb --selfcheck
```

> ⚠️ **Cowork:** selfcheck, запущенный тобой в песочнице, проверяет КОПИЮ внутри
> контейнера, а не машину пользователя. Не выдавай его за финальную проверку —
> попроси пользователя выполнить эти же команды у себя (или проверь живым
> вызовом MCP-инструмента после перезапуска клиента).

**Проверка авторизации из чата** (после перезапуска клиента) — инструмент `ozon_check_auth` / `wb_check_auth`: покажет активный кабинет, чего не хватает и где взять ключи. Секреты не эхает.

**Первый боевой вызов** — например, список товаров:
- Ozon: `ozon_get_products`
- WB: `wb_get_stocks` или `wb_get_sales`

Если вернулись реальные данные кабинета — установка прошла. Готово. (Это и есть
доказательство успеха — самоотчёту установщика `✅` не доверяй на 100%, пока не
прошёл живой вызов.)

---

## Troubleshooting

**«Python не установлен» / `command not found: python3`:**
- Поставить Python 3.10+ с https://python.org.
- **Windows:** при установке обязательно отметить галочку «Add python.exe to PATH», иначе `python`/`py` не найдутся. После установки — новый терминал.
- macOS: `python3` обычно есть; если нет — установить с python.org или `brew install python`.
- Двойной клик по `install.bat`/`install.command` сам подскажет, если Python не найден.

**`Client-Id should be positive integer` / `token malformed` / `token is malformed`:**
- Почти всегда означает, что сохранён ПУСТОЙ или НЕВЕРНЫЙ кабинет, и он ЗАТЕНЯЕТ переменные окружения (активный кабинет имеет приоритет над env).
- Проверь `~/.marketplace-mcp/cabinets.json`: посмотри активный кабинет и поля. Если там dummy/пусто — пересохрани реальные ключи (`install.py` или `*_add_cabinet`), либо удали кривой кабинет (`*_remove_cabinet`) и переключись на нужный (`*_use_cabinet`).
- Ozon `Client-Id` — это ЧИСЛО; если туда попала строка/мусор — ошибка про positive integer.

**WB: ошибка авторизации, хотя токен верный:**
- Известный нюанс: сервер шлёт токен в заголовке `Authorization` БЕЗ префикса `Bearer` (практика комьюнити). Если auth падает — это первое, что стоит проверить (см. caveats в README).
- Проверь, что в WB-токене отмечены нужные категории (Статистика/Цены/Контент). Токен без нужной категории даст 401/403 на этих методах.

**WB: rate limit (429 / «слишком много запросов»):**
- У WB Statistics API жёсткий лимит — порядка 1 запрос в минуту на ряд методов. Не дёргай подряд; при 429 подожди ~60 секунд.

**`git clone` падает в Cowork: `Operation not permitted` / `could not lock config file .git/config.lock`:**
- Это FUSE-монтирование хоста — git-locking/unlink на нём не работает. НЕ клонируй в подключённую папку.
- Обход: клонируй в `/tmp` и копируй без `.git` — `git clone … /tmp/mmru && rm -rf /tmp/mmru/.git && cp -R /tmp/mmru/. <папка>/`. Или просто работай с уже подключённой папкой (Вариант В) — `install.py` сам скопирует приложение наружу, git не нужен.

**Инструменты не появились после установки:**
- Перезапусти клиент (Claude Desktop / OpenCode читают конфиг при старте).
- Для Claude Code / Codex проверь, что ты реально ВЫПОЛНИЛ напечатанные `* mcp add` команды, а не только посмотрел их.
- Первый запуск ставит venv — если он упал (нет интернета/прав), запусти `python3 ~/.marketplace-mcp/app/serve.py ozon --selfcheck` вручную и прочитай stderr.
- Проверь `~/.marketplace-mcp/last_install.json`: указывает ли `serve_py` на существующий файл. Если папку-источник удалили ДО версии с канонической копией — переустанови (теперь конфиг привязан к `~/.marketplace-mcp/app`, не к месту клона).

**Ozon: метод 404 / 405 (Method Not Allowed):**
- Версии Ozon API дрейфуют (list v3, prices v5, stocks v4/v2). Если catalog-метод 404 — проверь версию или используй `ozon_get_raw` с правильным путём.
- Часть импортных эндпоинтов помечены GET, но реально POST (405). Это «карта для разведки» — уточни verb в доках или вызови через `*_get_raw` / `*_write_raw`.

---

## Памятка: что зависит от среды (anti-overpromise)

- **Claude Code / локальный CLI** → делаешь всё сам, до проверки включительно.
- **Cowork** → НЕ ставишь MCP сам. Двойной клик по установщику (computer-use) ИЛИ Claude Code ИЛИ пошаговый чеклист пользователю. Честно проговори границу песочницы.