Marketplaces MCP (RU) — Wildberries, Ozon, Yandex Market, Avito

marketplaces-mcp-ru：在你的 AI 助手中使用 Wildberries、Ozon、Яндекс Маркет 和 Авито

🇬🇧 英文版

将 AI 助手（Claude、Cursor、Codex、Cowork 等）直接连接到你的 Wildberries、Ozon、Яндекс Маркет 和 Авито 账户。你只需用日常语言提问，Agent 就会直接从各电商平台的 API（WB Seller API、Ozon Seller API、Yandex Market Partner API、Avito API）获取销售、订单、库存、价格、财务数据和评价，而不是凭空编造数字。

Быстрый старт, без установки в систему:

uvx marketplaces-mcp-ru

Зачем

Вы продаёте на нескольких площадках, а данные лежат в разных кабинетах. Продажи, остатки, цены, финансы, отзывы: всё руками, по очереди, через несколько браузеров. Обычный ИИ-ассистент тут мало помогает. Либо ходит через браузер и спотыкается о капчу, либо называет цифры, которые звучат уверенно, но взяты из воздуха.

Этот проект решает задачу иначе. Он даёт ассистенту прямой доступ к API всех четырёх площадок:

• Цифры приходят из ответа Wildberries, Ozon, Яндекс Маркета и Авито, с указанием источника и полей. Не пересказ, не догадка.
• Перед тем как менять цену или остаток, агент просит подтверждение. Случайно «уронить цену в три раза» не получится.
• Никакого браузера и капчи: обращение идёт по токену кабинета напрямую.

Спросите обычными словами: «покажи продажи за неделю на всех площадках», «что пора дозаказать», «сравни мои цены с рынком». Агент подберёт нужный метод или готовый сценарий и проведёт по шагам.

⚠️ Версия alpha. Помогает с операционкой продавца, но это инструмент, а не замена аналитику. Проверенное вручную ядро (продажи, остатки, цены, финансы, отзывы) выверено на реальных кабинетах. Остальные методы импортированы из спецификаций и служат картой для разведки. Подробности в разделе Оговорки.

Что можно спросить

Просто пишите агенту в чат по-русски:

покажи продажи за неделю на WB и Ozon и сравни
какие заказы на Яндекс Маркете ждут отгрузки сегодня
подтверди новые заказы Авито Доставки и покажи, где кончается остаток
что пора дозаказать, посчитай дни покрытия по остаткам и продажам
вытащи финотчёт реализации WB за прошлый месяц
какие товары на Ozon с красным индексом цены
собери отзывы ниже 4 звёзд за неделю и сгруппируй жалобы по товару
сделай ABC-анализ по выручке и покажи товары-хвост

Не знаете, с чего начать, скажите «что ты умеешь по моему кабинету». Агент покажет готовые сценарии: для Wildberries это пульс продаж, здоровье остатков, аудит цен, планировщик дозаказа, ABC-анализ, сводка отзывов; для Ozon: риск out-of-stock, анализ цен, юнит-экономика, синхронизация каталога, аудит контента и те же ABC и отзывы; для Яндекс Маркета: риск out-of-stock, анализ цен, разбор отзывов, индекс качества; для Авито: заказы на подтверждение, здоровье объявлений, расходы против результата, разбор отзывов. Каждый сценарий это пошаговый рецепт с трактовкой результата и типичными ошибками.

Установка

Подробный гайд под любую аудиторию лежит в QUICKSTART.md. Несколько способов, результат один.

1. Claude Desktop 一键安装（.mcpb）。 从 GitHub Releases 获取 marketplaces-mcp-ru-v<версия>.mcpb 并双击，Claude Desktop 会自动安装扩展，并在设置窗口中询问密钥。无需使用终端，也无需处理 Gatekeeper。一个程序包即可同时启动 WB + Ozon + Ozon Performance + Яндекс Маркет + Авито。
2. 让自己的 AI 帮忙（无需使用终端）。 打开 Claude 或 Cowork，然后说：“安装 marketplaces-mcp-ru”。Agent 会通过内置技能 marketplace-mcp-install/ 引导你操作。在 Cowork 沙盒中，最后一步点击仍需你亲自完成；在 Claude Code 中则会自动完成整个安装。
3. 通过目录中的技能安装。 npx skills add ilyautov/marketplaces-mcp-ru 会将技能 marketplace-mcp 添加给 Agent：之后它会自动安装服务、询问密钥并检查安装情况。适用于 Claude Code、Cursor 以及所有支持 Agent Skills 的工具。
4. 下载并点击。 从 GitHub Releases 获取 marketplaces-mcp-ru-v<версия>.zip，解压后双击 install.command（macOS）或 install.bat（Windows），然后粘贴密钥。在 macOS 上首次启动时：右键点击 →“打开”→“打开”（以此绕过 Gatekeeper 对下载文件的限制）。
5. 通过终端安装。 git clone https://github.com/ilyautov/marketplaces-mcp-ru，然后运行 python3 install.py --client <ваш-клиент>。
6. 面向开发者（npx / uvx）。 npx -y marketplaces-mcp-ru 与所有 MCP 客户端配置中的命令相同；无需安装 Python，npm 启动器会自动安装 uv，并从 PyPI 获取所需版本。uvx marketplaces-mcp-ru 会直接从 PyPI 启动整合服务；各独立服务可通过控制台命令 wb-mcp / ozon-mcp / ozon-perf-mcp / yandex-mcp / avito-mcp 启动。密钥可通过环境变量设置，也可在聊天中使用相同的 *_add_cabinet 工具添加。
7. VS Code / Cursor 一键安装。 本文上方的“安装”按钮会打开编辑器，并将 uvx marketplaces-mcp-ru 写入其 MCP 配置；VS Code 会立即询问密钥，Cursor 则需要在打开的 JSON 中填写密钥。
8. Docker。 docker run -i --rm -e WB_API_TOKEN=… -e OZON_CLIENT_ID=… -e OZON_API_KEY=… ghcr.io/ilyautov/marketplaces-mcp-ru 可通过 stdio 启动相同的整合服务，无需在机器上安装 Python。此镜像也作为 OCI 软件包列于 MCP Registry 中。若要远程访问，请添加 -e MCP_TRANSPORT=http -e MCP_HTTP_HOST=0.0.0.0 -p 8000:8000：服务将在 http://…:8000/mcp 上启动（Streamable HTTP）。HTTP 模式本身没有身份验证，请使用代理或防火墙限制访问。

仅使用一个市场平台。 如果不需要同时使用四个平台，这里还提供独立软件包：服务和目录相同，但只包含一个市场平台，并使用对应的平台名称。代码是共用的，通过依赖项从这里引入。

市场平台	软件包	方法数
Ozon Seller	ozon-mcp-ru	441
Wildberries	wildberries-mcp-ru	307
Яндекс Маркет	yandex-market-mcp-ru	165
Авито	avito-mcp-ru	64

安装程序会将应用复制到固定目录（~/.marketplace-mcp/app），并将配置指向该目录，因此之后可以移动或删除原始目录，不会影响运行。无需执行 pip install，也无需手动编辑 JSON：依赖项会在首次启动时自动安装。你只需要提供密钥。通过 --client 支持 4 种客户端：claude-desktop 和 opencode 会获得现成配置，claude-code 和 codex 会获得可直接使用的 mcp add 命令。 Где взять ключи. Wildberries: seller.wildberries.ru → Настройки → Доступ к API. Ozon: seller.ozon.ru → Настройки → API-ключи. Яндекс Маркет: partner.market.yandex.ru → Настройки → Доступ к API (Api-Key). Авито: avito.ru → Для бизнеса → Интеграции → API (client_id + client_secret). Ключи хранятся в ~/.marketplace-mcp/cabinets.json локально (chmod 600), в репозиторий и в чат не попадают. Можно подключить несколько магазинов и переключаться между ними прямо из чата (*_add_cabinet / *_use_cabinet).

Проверка после установки: одна команда показывает по всем пяти серверам, сколько инструментов и методов загрузилось, найдены ли ключи и где (кабинет / env), а с --live делает по одному реальному read-вызову в каждый кабинет.

python3 serve.py doctor --live          # из клона
uvx marketplaces-mcp-ru doctor --live   # из PyPI
npx -y marketplaces-mcp-ru doctor --live  # то же через npm, без Python

Код возврата 0 означает, что все настроенные кабинеты ответили. Секреты в вывод не попадают.

Безопасность

Ключ кабинета двигает цены, остатки и деньги, поэтому каждый метод заранее размечен по уровню риска:

• read: чтение, выполняется сразу;
• write: изменение, требует confirm_write=true;
• destructive: удаление, требует confirm_write=true и i_understand_this_modifies_data=true.

Проверка работает локально, наружу без подтверждения ничего не уходит. Что метод-мутация случайно не пометится как read, проверяет тест в CI (test_safety_catalog.py): сборка падает, если в каталог попадёт PUT, PATCH или DELETE с уровнем read. Дополнительно call_method подстраховывается на лету: даже устаревшая пометка read на мутирующем запросе не опустит проверку ниже write.

Подробнее в SECURITY.md. О найденной уязвимости пишите на [email protected] с темой SECURITY: marketplaces-mcp-ru, без публичного issue.

工作原理

底层由五个基于同一核心的 MCP 服务组成（Wildberries、Ozon Seller、Ozon Performance、Яндекс Маркет、Авито）。我们没有采用“每个端点对应一个工具”的方式（这会产生 300 多个工具，让 Agent 难以应对），而是采用了另一种设计：在方法目录之上提供通用元工具。以精简的工具集实现对 API 的完整覆盖。

ваш ИИ-агент
      │
      ▼
 мета-инструменты     ──►  каталог (endpoints.yaml)  ──►  общее ядро
 search / describe /                                      клиент · safety · ошибки
 call / write / delete /                                  пагинация · реестр
 raw · fetch_all / ...                                          │
 + типизированные инструменты (wb_get_sales, …)                 ▼
                          Wildberries / Ozon / Яндекс Маркет / Авито HTTPS API

所有服务上的元工具都相同（前缀为 wb_、ozon_、ozon_perf_、ym_ 或 avito_）：

工具	功能
*_check_auth	检查密钥是否存在（不会打印密钥）
*_search_methods	用俄语或英语搜索方法
*_describe_method	完整描述：方法、主机、路径、scope、风险等级、限流值、文档链接
*_call_method	读取：执行目录中 read 类别的方法，无需确认
*_write_method	写入：创建和修改数据，需要 confirm_write
*_delete_method	删除和不可逆修改，需要两项确认
*_get_raw	读取任意路径，即使该路径尚未收录在目录中（完整覆盖）
*_write_raw	向任意路径写入（POST、PUT、PATCH）
*_delete_raw	删除任意路径（DELETE）
*_fetch_all	自动分页（offset / last_id / cursor / WB 日期游标 / Маркет 页面令牌 / Авито 页码）

此外，还有用于常见任务的类型化工具（wb_get_sales、wb_get_stocks、ozon_get_products、ozon_get_prices、ym_get_orders、ym_set_price、avito_get_orders、avito_update_stock 等），以及用于管理店铺后台的工具。

目录根据官方 OpenAPI 规范以 schema 驱动方式构建：

目录	文件	方法数	分区数
Wildberries	wb_mcp/endpoints.yaml	307	70
Ozon Seller	ozon_mcp/endpoints.yaml	441	67
Ozon Performance（广告）	ozon_mcp/perf_endpoints.yaml	45	6
Яндекс Маркет（Partner API）	yandex_mcp/endpoints.yaml	165	29
Авито（商业 API）	avito_mcp/endpoints.yaml	64	8

核心功能（销售、库存、价格、财务、评价）已通过实际测试验证；其余功能从规范导入，而 get_raw 可以访问尚未收录在目录中的内容。各业务领域的覆盖范围如下：

领域	Wildberries	Ozon
销售和订单	销售、订单、FBS / DBS / DBW / 自提组装任务	FBO / FBS 订单、发货、退货
库存和仓库	库存、卖家仓库、FBS 供货	各仓库库存、FBO / FBS、库存分析
价格和折扣	价格和折扣、促销日历	价格、定价策略、促销
财务	销售财务报告、余额	交易、应计款项、销售、补偿
内容和商品卡片	商品卡片、类别、属性、媒体	商品、属性、类别、证书
评价和问题	评价、问题	评价（需要 Premium Plus）、问题和回答
广告	广告活动管理、统计数据	Performance API（独立服务）

Яндекс Маркет 和 Авито（在 0.5.0 中新增）：

领域	Яндекс Маркет	Авито
订单	FBS / DBS / Express 订单、状态、退货、发货	Авито Доставка 订单、确认、追踪号码、标记
商品和库存	商品目录、商品卡片、各仓库库存、隐藏商品	商品刊登、刊登商品的库存、自动上传
价格	价格、价格隔离、促销、建议	刊登价格
评价和聊天	评价、问题、与买家的聊天	评分、评价和回答、即时消息
分析	订单和商品统计数据、27 份报告、质量指数	浏览量和联系量、支出、来电
推广	销量提升、竞价	推广服务、BBIP
分析	销售漏斗、报告	分析报告、库存周转率

在聊天中运行 *_list_sections 可查看完整分区列表；要进行定向搜索，可运行 wb_search_methods("остатки")。

开发

本节面向想要深入研究代码、实战验证方法或提交 PR 的人。

结构。 所有通用逻辑都位于 core/，各服务只是对其进行的轻量封装：

core/                общее ядро всех серверов
  client.py          HTTPS-клиент (хосты, заголовки, ретраи)
  credentials.py     загрузка ключей из cabinets.json / env
  safety.py          гейт read / write / destructive
  registry.py        загрузка и индексация каталога endpoints.yaml
  paginate.py        авто-пагинация (offset / last_id / cursor / date / pageToken / page)
  entities.py        нормализация сущностей (товары, заказы и т.д.)
  workflows.py       движок пошаговых сценариев
  tools.py           регистрация мета-инструментов в MCP
  transport.py       выбор транспорта: stdio (по умолчанию) или Streamable HTTP
  doctor.py          диагностика: инструменты, каталоги, ключи, живой пинг
  errors.py          единый формат ошибок
wb_mcp/              сервер WB: server.py + endpoints.yaml + workflows.yaml
ozon_mcp/            сервер Ozon: server.py + endpoints.yaml + perf_endpoints.yaml + workflows.yaml
ozon_perf_mcp/       сервер Ozon Performance (реклама, OAuth2)
yandex_mcp/          сервер Яндекс Маркета: server.py + endpoints.yaml + workflows.yaml
avito_mcp/           сервер Авито: server.py + endpoints.yaml + workflows.yaml (OAuth2)
scripts/             сборка каталогов, валидация, релиз
tests/               офлайн-тесты (токены не нужны)

本地运行和测试。 需要 Python 3.10+。serve.py 会在首次运行时将依赖项（mcp、httpx、pyyaml）自行安装到本地 .venv 中。

git clone https://github.com/ilyautov/marketplaces-mcp-ru.git
cd marketplaces-mcp-ru

# офлайн-тесты, ключи не нужны — все офлайн-тесты зелёные
env -u OZON_CLIENT_ID -u OZON_API_KEY -u WB_API_TOKEN python3 -m pytest tests/ -q

# selfcheck серверов: 21 тул для wb, 21 для ozon, 16 для ozon-perf, 22 для yandex, 26 для avito
python3 serve.py wb --selfcheck
python3 serve.py ozon --selfcheck
python3 serve.py ozon-perf --selfcheck
python3 serve.py yandex --selfcheck
python3 serve.py avito --selfcheck

# всё сразу: инструменты, каталоги, ключи, живой пинг кабинетов
python3 serve.py doctor --live

# образ для MCP Registry / удалённого запуска
docker build -t marketplaces-mcp-ru .
docker run --rm marketplaces-mcp-ru doctor

传输方式。 默认使用 stdio，这是 Claude Desktop、Cursor、Codex 和 Claude Code 所需的方式。MCP_TRANSPORT=http 可将任意服务（以及合并服务）切换为 Streamable HTTP：MCP_HTTP_HOST（默认为 127.0.0.1）、MCP_HTTP_PORT（8000）、MCP_HTTP_ALLOWED_HOSTS（以逗号分隔的允许使用的 Host 标头列表），用于在对外发布时防范 DNS 重绑定攻击。HTTP 模式没有身份验证：能连接到该端口的人就能使用你的密钥。请将其限制在 localhost 上，或置于代理之后。

目录的构建与扩展方式。 endpoints.yaml 根据官方 OpenAPI 规范以 schema 驱动的方式生成：ingest_specs.py（WB）和 ingest_ozon.py（Ozon）会拉取路径，derive_pagination.py 和 fix_items_path_from_examples.py 会配置分页和 items_path，sync_swagger.py 会拉取最新规范。每个方法的条目都会描述 operation_id、方法、主机、路径、scope、风险级别和分页。导入具有幂等性且只会添加内容：经过人工整理的风险级别和描述不会被覆盖。validate_items_path.py 是实时验证工具（请使用自己的密钥在本地运行），package_release.py 会打包干净的版本 zip，smoke_mcp.py 是冒烟测试。

特别欢迎以下贡献：

• 实战验证 HTTP 动词。导入方法的路径可靠，但动词不一定可靠：实时探测发现过实际上应为 POST 的“GET”（返回 405）。请修改 */endpoints.yaml 并附上证明：响应代码或文档链接。
• 在 */workflows.yaml 中添加新场景：包含解释和常见错误的分步指南，每一步都要与目录中的内容核对。
• 如果方法的标记过于宽松或严格，请改进其安全分类。

完整规则请见 CONTRIBUTING.md。提交 PR 前，请运行离线测试以及所有服务的 --selfcheck；如果方法或工具的数量发生变化，请更新 README 中的数字。

仓库安全。 面向人员和 Agent 的指南位于 AGENTS.md。密钥仅保存在本地：.env、cabinets.json、密钥和证书均由 .gitignore 排除，pre-commit 会运行 scripts/security/forbid_sensitive_files.py 和 scan_mcp_config.py。测试 test_safety_catalog.py 可确保带有 read 标记的变更方法不会进入目录：如果 PUT、PATCH 或 DELETE 被标记为 read，构建就会失败。.mcp.json 是有意纳入版本控制的，它是一个不含密钥的插件清单。

常见问题

需要会编程吗？ 不需要。可以选择“让你的 AI 来安装”，也可以双击安装。不需要执行 pip install 或编辑 JSON，依赖项会自动安装，你只需要提供 API 密钥。

安全吗？密钥会发送到哪里？ 服务和你的 Agent 一样，都在本地运行。密钥保存在 ~/.marketplace-mcp/cabinets.json（chmod 600），不会进入代码仓库或聊天。对店铺进行的任何更改（价格、库存）都需要你确认后才会生效。

它比解析器和浏览器机器人好在哪里？ 它通过令牌直接调用 Seller API，而不是解析网页：没有验证码，也不会被封锁，数据以结构化形式返回。此外，还能防止意外更改价格或库存。

它免费吗？ 是的，代码以 MIT 许可证开源。欢迎使用、分叉和改进。

支持 Yandex Market 和 Avito 吗？ 支持，从 0.5.0 版本开始。Yandex Market 使用合作伙伴后台中的 Api-Key 接入（Partner API：订单、商品、库存、价格、报告、聊天、质量指数）。Avito 使用“集成”部分中的一对 client_id / client_secret 接入（Avito 配送订单、商品库存和价格、统计数据、评价、即时通信、推广）。yandex-mcp 和 avito-mcp 服务既可独立运行，也可作为整合服务的一部分运行。

什么是 MCP？它对卖家有什么用？ MCP（Model Context Protocol）是一种开放标准，AI 助手可以通过它接入外部工具。本项目是面向电商平台的 MCP 服务：它将 Wildberries、Ozon、Yandex Market 和 Avito 的 API 转换为工具，Agent 可以根据你用俄语提出的问题自行调用这些工具。

注意事项

请对照电商平台的最新文档进行核实：

• WB Authorization：服务会发送不带 Bearer 前缀的原始令牌（已通过实践验证）。如果授权失败，请优先检查这一点。
• 从规范导入的方法：路径可靠，但 HTTP 方法不一定正确。 在线测试发现，某些标记为 GET 的方法实际上是 POST（返回 405）。请将这类条目视为探索地图：根据文档确认方法和请求体，或通过原始工具调用。经过整理的核心（WB 的 7 个类别、Ozon 的 4 个部分）和经过在线验证的工具集可靠。
• Ozon 的版本会变化（list v3、attributes v4、prices v5）。遇到 404 时请检查版本；ingest_ozon.py 会重新对齐路径。
• Ozon Performance：目前只有目录产物和根据文档实现的 OAuth 封装。令牌端点协议尚未在实际环境中验证，需要广告凭据。
• Yandex Market 和 Avito（0.5.0 版本新增）：目录基于官方 OpenAPI 文档构建，类型化工具根据规范编写，但尚未在真实店铺后台进行实际测试。字段名称可能有误，describe_method 和原始工具可帮助你当场修正请求。
• 店铺配置会覆盖环境变量。 cabinets.json 中的活动店铺配置优先于 env。遇到无法解释的 401 或“Client-Id should be positive integer”，请先检查此文件。

这不是什么

这是供 AI Agent 使用的工具，不是一键式在线服务，也不能替代分析师。是否更改价格、库存或资金，始终由你决定；保护机制只是防止意外操作。本项目处于 alpha 阶段：请自行安装并使用自己的数据进行测试和实验。如果发现问题，请创建 issue（不要提供真实密钥或店铺数据）。

架构借鉴了成熟 marketplace-MCP 项目的优秀理念（schema 驱动的目录、安全检查、统一的错误格式、自动分页），但使用自己的代码实现，不依赖其他库。

许可证

MIT。

---

Кто это сделал

Илья Утов, лаборатория AI Frontier. Как эти инструменты устроены внутри, пишу в Telegram и LinkedIn.

Рядом стоят:

• humanizer-ru: убирает следы нейросети из русского текста
• small-business-ru: 34 скилла для малого бизнеса, считают налоги и проверяют контрагента по ИНН
• consilium-principis: совет мыслителей, где каждая цитата сверяется дословно
• hefest: химическая безопасность завода, целиком офлайн
• cordon: детерминированный слой между недоверенным контентом и действиями агента

Все проекты одним списком, разобранные по назначению: ilyautov.github.io. Исходники: github.com/ilyautov. Пригодилось, поставьте звезду: по ней это находят другие.