Content
# Tool List
> 🇬🇧 [English version](README.en.md)
> **Sell on WB and Ozon — give AI direct access to both accounts.** Two MCP servers over Seller API Wildberries and Ozon: **793 methods** (sales, stocks, prices, finances, reviews, supplies, advertising), collected schema-driven from official OpenAPI specs. Numbers come from **real API**, not invented by the model. **Safety gate** doesn't allow accidentally changing price or stock. Auto-pagination, multi-account, Russian search. For Claude Code, Cursor, Codex, Cowork and Claude Desktop.
[](LICENSE)
[](https://github.com/ilyautov/marketplaces-mcp-ru/commits/main)
[](#what-is-inside)
[](#installation)
[](https://github.com/ilyautov/marketplaces-mcp-ru/stargazers)
<!-- social preview: assets/social-preview.png → загрузить в Settings → Social preview.
TODO: сайт marketplaces-mcp-ru.aifrontier.tech (как у humanizer-ru / small-business-ru) -->
## Why This Is Needed
**You sell on two marketplaces at the same time, and data is in two different accounts.** Sales, stocks, prices, finances, reviews — everything manually, through two browsers, one by one. AI assistant is usually useless: either it goes through the browser and stumbles upon captchas or makes up numbers that sound confident.
`marketplaces-mcp-ru` takes a different approach — gives AI agent **direct access to Seller API of both accounts**:
- **Numbers from real API, not from the model's head.** Sales, stocks, margin, financial report — it's a response from Wildberries and Ozon, with source and fields, not a plausible invention.
- **Safety gate for everything that affects money.** Each method is marked as `read` / `write` / `destructive`; reading goes immediately, and changing price or stock requires explicit confirmation. You can't accidentally "drop the price by 3 times".
- **No browser and captchas.** Direct HTTPS requests by account token.
Tell the agent in simple words: "show sales for a week on both", "what needs to be reordered", "compare prices with the market" — it will pick a method or a ready scenario and go through the steps.
> ⚠️ **alpha.** Helps with seller operations, but it's a tool, not a replacement for an analyst. The curated core is battle-tested on real accounts; imported methods from specs are a map for reconnaissance (paths are reliable, HTTP verbs confirm according to docs). Details — in the "Caveats" section below.
## What Is Inside
**Not "one tool per endpoint" (that's 300+ tools, which the agent gets lost in), but 8 generic meta-tools over the catalog** — full API coverage with a small surface.
```
your AI agent
│
▼
8 meta-tools ──► catalog (endpoints.yaml) ──► common core
search / describe / client · safety · errors
call / call_raw / pagination · registry
fetch_all / ... │
+ typed tools (wb_get_sales, ozon_get_prices, …) ▼
Wildberries / Ozon HTTPS API
```
**Meta-tools (same set for both servers, prefix `wb_` / `ozon_`):**
| Tool | What it does |
|---|---|
| `*_check_auth` | Are there credentials (secrets are not printed) |
| `*_search_methods` | Method search — **in Russian or English** |
| `*_describe_method` | Full spec: method, host, path, scope, safety, limit, doc |
| `*_call_method` | Call any catalog method (through safety gate) |
| `*_call_raw` | Call **any** path, even outside the catalog (100% coverage) |
| `*_fetch_all` | Auto-pagination (offset / last_id / cursor / WB date-cursor) |
Plus typed convenient tools (`wb_get_sales`, `wb_get_stocks`, `ozon_get_products`, `ozon_get_prices`, …) and account tools.
**Scenarios (workflows) — not raw endpoints, but recipes.** `*_list_workflows` / `*_get_workflow` give step-by-step recipes with interpretation and typical errors. WB: `sales_pulse`, `stock_health`, `price_audit`, `reorder_planner`, `abc_analysis`, `reviews_pulse`. Ozon: `oos_risk_analysis`, `pricing_analysis`, `unit_economics`, `catalog_sync`, `content_quality_audit`, `abc_analysis`, `reviews_pulse`. Each step is verified with the catalog.
**Coverage — schema-driven from official OpenAPI specs:**
| Catalog | File | Methods | Sections |
|---|---|---:|---|
| Wildberries | `wb_mcp/endpoints.yaml` | **307** | 70 |
| Ozon Seller | `ozon_mcp/endpoints.yaml` | **441** | 67 |
| Ozon Performance (advertising) | `ozon_mcp/perf_endpoints.yaml` | **45** | 6 |
The curated core (sales/stocks/prices/finances/reviews) is battle-tested; the rest is imported from specs. `call_raw` retrieves everything that's not in the catalog yet.
### Method Sections — what's covered on both marketplaces
Raw catalog sections are grouped by business areas:
| Area | Wildberries | Ozon |
|---|---|---|
| Sales and orders | sales, orders, assembly tasks FBS / DBS / DBW / Self-pickup | orders FBO / FBS, shipments, returns |
| Stocks and warehouses | stocks, seller warehouses, FBS supplies | stocks by warehouses, FBO / FBS, stock analytics |
| Prices and discounts | prices and discounts, promotions calendar | prices, pricing strategies, promotions |
| Finances | implementation financial report, balance | transactions, accruals, implementation, compensations |
| Content and cards | cards, categories, characteristics, media | products, attributes, categories, certificates |
| Reviews and questions | reviews, questions | reviews (Premium Plus required), questions and answers |
| Advertising | campaign management, statistics | Performance API (separate server) |
| Analytics | sales funnel, reports | analytical reports, turnover |
Full list of sections — `*_list_sections` directly in the chat, or search: `wb_search_methods("stocks")`.
## What You Can Ask
Ask the agent in Russian, in simple words:
```
show sales for a week on WB and Ozon and compare
what needs to be reordered — calculate coverage days by stocks and sales
pull the financial report for WB implementation for last month
which products on Ozon with a red price index are candidates for reduction
collect reviews below 4 stars for a week and group complaints by product
make ABC analysis by revenue and show tail products
```
Not sure where to start — say **"what you can do with my account"** or call `wb_list_workflows` / `ozon_list_workflows`: ready scenarios with interpretation and typical errors.
## Before and After
**Analytics "by eye", by one account in the browser:**
> Went to the WB account, roughly estimated what's selling. Didn't get to Ozon. What needs to be reordered — decided from memory.
**With `marketplaces-mcp-ru`:**
> The agent pulled sales and stocks from both accounts via API, calculated ADS and coverage days with a script, and output a list "to reorder first" with numbers. Compared Ozon prices with the market index, marked red ones. Everything — from real API responses, not from the model's head, and without the risk of accidentally changing prices (safety gate for writing).
## Safety Model
Account keys affect prices, stocks, and money. Each method is classified:
- **read** → executed immediately;
- **write** → requires `confirm_write=true`;
- **destructive** → requires `confirm_write=true` **and** `i_understand_this_modifies_data=true`.
The gate works locally — no confirmations go outside. **0 mutations marked as read** in all three catalogs — this is verified by a test in CI (`test_safety_catalog.py`), not just words: the build fails if a PUT/PATCH/DELETE with `safety: read` gets into the catalog. Additionally, `call_method` is insured on the fly — even an outdated `read` on a mutating verb won't lower the gate below `write`.
## Installation
A detailed step-by-step guide for any audience is available in **[QUICKSTART.md](QUICKSTART.md)**. Three paths, one result:
1. **The easiest way - ask your AI (without terminal).** Open Claude / Cowork and say: *«install WB + Ozon MCP»* — the agent will guide you through the built-in `install-skill/`. (The Cowork sandbox does not access your machine, so the final click remains yours — the skill only brings you to the point without errors. In Claude Code, it is installed fully automatically.)
2. **Download and click.** Take `marketplaces-mcp-ru-v<version>.zip` from [GitHub Releases](https://github.com/ilyautov/marketplaces-mcp-ru/releases), unpack, double-click `install.command` (macOS) / `install.bat` (Windows), and insert the keys. _macOS, first time: right-click → «Open» → «Open» (to bypass Gatekeeper for the downloaded file)._
3. **Technical.** `git clone https://github.com/ilyautov/marketplaces-mcp-ru` → `python3 install.py --client <your-client>`.
The installer **copies the application to a stable location** (`~/.marketplace-mcp/app`) and binds the config there — the downloaded or connected folder can then be moved and deleted, and MCP will not break. No `pip install`, no JSON edits: dependencies are installed automatically at the first launch (local venv), and all you need to do is provide the keys. **4 clients** via `--client`: `claude-desktop` and `opencode` receive a recorded config, `claude-code` and `codex` — ready `* mcp add` commands.
**Where to get the keys:** Wildberries — seller.wildberries.ru → Settings → API Access; Ozon — seller.ozon.ru → Settings → API Keys. Keys are stored in `~/.marketplace-mcp/cabinets.json` (locally, chmod 600, never in the repo). Support for **multi-cabinet** — several stores with switching from the chat (`*_add_cabinet` / `*_use_cabinet`).
**Verification after installation:**
```bash
python3 serve.py ozon --selfcheck
```
## Scripts and catalog growth
In `scripts/`: `ingest_specs.py` / `ingest_ozon.py` (catalog assembly from official specs), `derive_pagination.py` and `fix_items_path_from_examples.py` (pagination and `items_path`), `validate_items_path.py` (**live**-validator, run locally), `package_release.py` (pure version zip), `smoke_mcp.py`. Catalogs grow additively and idempotently — curated safety and descriptions are not overwritten.
## Tests
```bash
python3 -m pytest tests/ -q # 21 offline tests, no tokens needed
```
## Frequently Asked Questions
**How to connect AI to Wildberries and Ozon API?** Install `marketplaces-mcp-ru` — two MCP servers give your agent (Claude, Cursor, Codex, ChatGPT via MCP) direct access to Seller API of both cabinets by token. No browser and no captcha.
**Is there a ready-made MCP server for Wildberries / Ozon Seller API?** Yes, this is it. Schema-driven catalog from official OpenAPI specs: 307 methods WB + 441 Ozon + 45 Ozon Performance, search in Russian, auto-pagination.
**How to give Claude or ChatGPT access to WB / Ozon cabinet?** Through MCP. Once you install the server (double-click installer or `install.py`), enter the cabinet token — then the agent calls the necessary methods itself. The key is stored locally (chmod 600), not in the chat.
**How to get sales, balances, prices, and finances of WB / Ozon through API in AI?** Ask in simple words — the agent will select a method (`wb_get_sales`, `ozon_get_prices`, …) or scenario and return data from a real API response.
**Can it be done without 1C and programming?** Yes. No `pip install` and JSON edits: dependencies are installed automatically, and all you need to do is provide the API key. For non-technical users, there is an installation «ask your AI» and double-click.
**How is it different from parsers and browser bots?** This is a direct Seller API by token, not page parsing: no captcha, no blocks, structured data. Plus, the safety gate does not allow you to accidentally change the price or balance.
**Is it free?** Yes, open code under MIT. Take it, fork it, and improve it.
**Is it safe, where do the keys go?** The server works where your agent is (locally). Keys are stored in `~/.marketplace-mcp/cabinets.json` (chmod 600), not in the repository or chat. Writing to the cabinet (changing price/balance) — only with explicit confirmation.
## Caveats (check with live documentation)
- **WB `Authorization`**: the server sends **raw-token without `Bearer`** (confirmed by battle). If auth falls, first check this.
- **Imported methods from specs: paths are reliable, HTTP verbs are not.** Live test found GET-marked methods that are actually POST (405). Consider imported records as a reconnaissance map: confirm the verb/body according to the documentation or call via `call_raw`. Curated core (WB 7 categories, Ozon 4 sections) and live-verified set — reliable.
- **Ozon drifts by versions** (list v3, attributes v4, prices v5). If you get a 404, check the version; `ingest_ozon.py` re-aligns paths.
- **Ozon Performance** — so far, a catalog artifact + OAuth binding according to the documentation (the token-endpoint contract is not verified by battle, advertising credentials are needed).
- **Cabinet overrides env**: the active cabinet in `cabinets.json` has priority over environment variables. Unexplained 401 / «Client-Id should be positive integer» — first check the store.
## What it is not
A tool for an agent, not an online service «in one click» and not a replacement for an analyst. The curated core is battle-tested, but imported methods from specs should be confirmed according to the documentation. A solution that affects prices, balances, or money always remains yours — the safety gate only prevents accidental changes. This is alpha and open code: **install, test on your data, experiment.** Found a bug — create an [issue](https://github.com/ilyautov/marketplaces-mcp-ru/issues).
Proprietary code, best patterns: architecture takes the strongest ideas of mature marketplace-MCP (schema-driven catalog, safety gate, unified errors, auto-pagination) without dependency on third-party libraries.
---
**marketplaces-mcp-ru** — open MCP server for Wildberries and Ozon cabinets: sales, balances, prices, finances, reviews, deliveries, and advertising through Seller API directly, without browser and captcha. Connects AI agent (Claude Code, Cursor, Codex, Cowork, Claude Desktop, ChatGPT via MCP) to WB and Ozon API. Schema-driven catalog from official OpenAPI specs (793 methods), safety gate for recording, auto-pagination, multi-cabinet, search in Russian. Free open-source under MIT. Numbers — from a real API response, not from the model's imagination.
Connection Info
You Might Also Like
No recommendations available