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

marketplaces-mcp-ru：Wildberries、Ozon、Яндекс Маркет、АвитоをAI アシスタントで利用

🇬🇧 英語版

AI アシスタント（Claude、Cursor、Codex、Cowork など）を、Wildberries、Ozon、Яндекс Маркет、Авитоの各アカウントに直接接続します。普通の言葉で質問すると、エージェントはマーケットプレイスの 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 も不要です。1つのバンドルで WB + Ozon + Ozon Performance + Яндекс Маркет + Авито がすべて起動します。
2. 自分の AI に頼む（ターミナル不要）。 Claude または Cowork を開き、「marketplaces-mcp-ru をインストールして」と伝えてください。エージェントが組み込みスキル marketplace-mcp-install/ を使って案内します。Cowork のサンドボックスでは最後のクリックはご自身で行う必要がありますが、Claude Code ではインストールがすべて自動で完了します。
3. カタログからスキルを使う。 npx skills add ilyautov/marketplaces-mcp-ru を実行すると、エージェントにスキル marketplaces-mcp が追加されます。その後、エージェントが自分でサーバーをインストールし、キーを尋ねて、インストールを確認します。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 にワンクリックでインストール。 このテキストの上にある「インストール」ボタンをクリックするとエディターが開き、その MCP 設定に uvx marketplaces-mcp-ru が追加されます。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 を実行すると、マシンに Python をインストールせずに、stdio 経由で同じ統合サーバーを起動できます。このイメージは MCP Registry に OCI パッケージとして登録されています。リモートアクセスを有効にするには、-e MCP_TRANSPORT=http -e MCP_HTTP_HOST=0.0.0.0 -p 8000:8000 を追加してください。サーバーは http://…:8000/mcp（Streamable HTTP）で起動します。HTTP モードには独自の認証機能がないため、プロキシまたはファイアウォールで保護してください。

マーケットプレイスを1つだけ使う場合。 4つのマーケットプレイスすべてが必要でなければ、個別パッケージもあります。同じサーバーと同じツール一覧を備えていますが、対象のマーケットプレイスは1つで、検索に使う名前も個別です。コードは共通で、このリポジトリを依存関係として取得します。

マーケットプレイス	パッケージ	メソッド数
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.

仕組み

内部では、共通のコア上で5つのMCPサーバー（Wildberries、Ozon Seller、Ozon Performance、Яндекс Маркет、Авито）が動作しています。「エンドポイントごとに1つのツール」を用意する方式では、ツールが300個以上になり、エージェントが迷ってしまいます。そこで、メソッドカタログを利用する汎用メタツール方式を採用しました。コンパクトなツール群で、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	メソッド、ホスト、パス、スコープ、リスクレベル、制限、ドキュメントへのリンクを含む詳細情報を表示します
*_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 の日付カーソル / マーケットの pageToken / Авито の page）

さらに、よくあるタスク向けの型付きツール（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仕様からスキーマ駆動で生成されています。

カタログ	ファイル	メソッド数	セクション数
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 / エクスプレス注文、ステータス、返品、出荷	Авито 配送の注文、確認、追跡番号、ラベル付け
商品と在庫	カタログ、商品カード、倉庫別在庫、非表示商品	出品、出品中の商品在庫、自動アップロード
価格	価格、価格の検疫、プロモーション、レコメンデーション	出品価格
レビューとチャット	レビュー、質問、購入者とのチャット	評価、レビューと回答、メッセンジャー
分析	注文と商品の統計、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 以降が必要です。依存関係（mcp、httpx、pyyaml）は、初回起動時に serve.py がローカルの .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 仕様からスキーマ駆動で生成されます。ingest_specs.py（WB）と ingest_ozon.py（Ozon）がパスを取得し、derive_pagination.py と fix_items_path_from_examples.py がページネーションと items_path を設定し、sync_swagger.py が最新の仕様を取得します。各メソッドのエントリーには、operation_id、メソッド、ホスト、パス、スコープ、リスクレベル、ページネーションが記述されています。インポートは冪等かつ追加型で、手動設定したリスクレベルや説明が上書きされることはありません。validate_items_path.py はライブバリデーターです（自身のキーを使ってローカルで実行してください）。package_release.py はクリーンなバージョン付き zip を作成し、smoke_mcp.py はスモークテストを実行します。

特に役立つ貢献：

• HTTP メソッドの実地検証。インポートされたメソッドのパスは信頼できますが、HTTP メソッドはそうとは限りません。ライブ検証で、実際には POST なのに「GET」とされているもの（405）が見つかっています。*/endpoints.yaml を修正し、証拠としてレスポンスコードまたはドキュメントへのリンクを添えてください。
• */workflows.yaml への新しいシナリオ。解説とよくあるエラーを含む手順形式のレシピを作成し、各ステップをカタログと照合してください。
• メソッドの安全性分類の見直し。分類が厳しすぎる、または甘すぎる場合に修正してください。

詳細なルールは CONTRIBUTING.md をご覧ください。PR を送る前に、オフラインテストとすべてのサーバーの --selfcheck を実行してください。メソッド数またはツール数を変更した場合は、README の数値も更新してください。

リポジトリのセキュリティ。 人間とエージェント向けのガイドラインは AGENTS.md にあります。シークレットはローカルにのみ保存します。.env、cabinets.json、キー、証明書は .gitignore で除外され、pre-commit では scripts/security/forbid_sensitive_files.py と scan_mcp_config.py が実行されます。変更を伴うメソッドが read レベルでカタログに登録されないよう、テスト test_safety_catalog.py で検証しています。read とマークされた PUT、PATCH、DELETE があると、ビルドは失敗します。.mcp.json は意図的に追跡対象です。シークレットを含まないプラグインマニフェストだからです。

よくある質問

プログラミングの知識は必要ですか？ いいえ。「AI に頼む」インストール方法と、ダブルクリックでのインストール方法があります。pip install や JSON の編集は不要で、依存関係も自動でインストールされます。必要なのは API キーだけです。

安全ですか？キーはどこに保存されますか？ サーバーはエージェントと同じ場所で、ローカルに動作します。キーは ~/.marketplace-mcp/cabinets.json（chmod 600）に保存され、リポジトリやチャットに送信されることはありません。キャビネットへの変更（価格、在庫数）は、すべてお客様の確認後にのみ行われます。

パーサーやブラウザーボットより優れている点は何ですか？ ウェブページを解析するのではなく、トークンを使って Seller API に直接アクセスします。CAPTCHA やブロックがなく、データは構造化された形式で取得できます。さらに、価格や在庫数を誤って変更することを防ぐ機能もあります。

無料ですか？ はい。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 をツールに変換し、エージェントがお客様のロシア語での質問に応じて呼び出します。

注意事項

マーケットプレイスの最新のドキュメントと照らし合わせて確認してください。

• WB Authorization：サーバーは Bearer プレフィックスなしの raw トークンを送信します（実際の動作で確認済み）。認証に失敗した場合は、まずここを確認してください。
• 仕様からインポートしたメソッド：パスは信頼できますが、HTTP メソッドは常に正しいとは限りません。 実機でのテストでは、GET と表示されていたメソッドが実際には POST（405 エラー）であるケースが見つかりました。こうした記録は調査の手がかりとして扱い、ドキュメントで HTTP メソッドとリクエスト本文を確認するか、raw ツールから呼び出してください。厳選されたコア（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 と raw ツールを使えば、その場でリクエストを修正できます。
• キャビネットの設定は環境変数より優先されます。 cabinets.json で有効になっているキャビネットは、環境変数より優先されます。原因不明の 401 や「Client-Id should be positive integer」が発生した場合は、まずこのファイルを確認してください。

このプロジェクトの対象外

これは AI エージェント向けのツールであり、「ワンクリック」で使えるオンラインサービスでも、アナリストの代わりでもありません。価格、在庫数、または資金に変更を加える判断は、常にお客様に委ねられています。保護機能は、誤操作を防ぐためのものです。プロジェクトはアルファ段階です。インストールしてご自身のデータで確認し、試してみてください。問題を見つけた場合は、issue を作成してください（実際のキーやキャビネットのデータは含めないでください）。

アーキテクチャは、成熟したマーケットプレイス向け MCP の優れたアイデア（スキーマ駆動のカタログ、安全性の検証、統一されたエラー形式、自動ページネーション）を取り入れていますが、外部ライブラリに依存せず、独自のコードで実装しています。

ライセンス

MIT。

---

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

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

Рядом стоят:

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

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