ru-marketplace-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| WB_PROXY | No | Proxy URL for Wildberries requests, overrides standard proxy settings. | |
| OZON_PROXY | No | Proxy URL for Ozon tier-1 requests. | |
| WB_MIN_GAP | No | Minimum gap between Wildberries requests (seconds). | |
| WB_TIMEOUT | No | Timeout for Wildberries HTTP requests (seconds). | |
| AVITO_PROXY | No | Proxy URL for Avito tier-1 requests. | |
| DNS_MIN_GAP | No | Minimum gap between DNS requests (seconds). | |
| DNS_TIMEOUT | No | Timeout for DNS HTTP requests (seconds). | |
| DETMIR_PROXY | No | Proxy URL for Detsky Mir requests. | |
| LAMODA_PROXY | No | Proxy URL for Lamoda requests. | |
| OZON_MIN_GAP | No | Minimum gap between Ozon requests (seconds). | |
| OZON_TIMEOUT | No | Timeout for Ozon HTTP requests (seconds). | |
| TAOBAO_PROXY | No | Proxy URL for Taobao requests. | |
| WB_CACHE_TTL | No | Cache TTL in seconds for Wildberries (0 disables). | |
| YANDEX_PROXY | No | Proxy URL for Yandex Market requests. | |
| AVITO_MIN_GAP | No | Minimum gap between Avito requests (seconds). | |
| AVITO_TIMEOUT | No | Timeout for Avito HTTP requests (seconds). | |
| CHROME_BINARY | No | Path to the Chrome/Chromium binary. | |
| DETMIR_REGION | No | Default region for Detsky Mir (e.g., RU-MOW, RU-SPE). | |
| DNS_CACHE_TTL | No | Cache TTL in seconds for DNS (0 disables). | |
| MCP_HTTP_HOST | No | Host to bind for HTTP transport. | |
| MCP_HTTP_PORT | No | Port to bind for HTTP transport. | |
| MCP_TRANSPORT | No | Transport for the MCP server: 'stdio' (default) or 'http'. | |
| MPSTATS_PROXY | No | Proxy URL for MPStats requests. | |
| CHROME_STEALTH | No | Enable stealth mode for Chrome (e.g., 'true' or 'false'). | |
| LAMODA_MIN_GAP | No | Minimum gap between Lamoda requests (seconds). | |
| LAMODA_TIMEOUT | No | Timeout for Lamoda HTTP requests (seconds). | |
| OZON_CACHE_TTL | No | Cache TTL in seconds for Ozon (0 disables). | |
| TAOBAO_MIN_GAP | No | Minimum gap between Taobao requests (seconds). | |
| TAOBAO_TIMEOUT | No | Timeout for Taobao HTTP requests (seconds). | |
| WB_NET_RETRIES | No | Number of network retries for Wildberries. | |
| YANDEX_MIN_GAP | No | Minimum gap between Yandex Market requests (seconds). | |
| YANDEX_TIMEOUT | No | Timeout for Yandex Market HTTP requests (seconds). | |
| AVITO_CACHE_TTL | No | Cache TTL in seconds for Avito (0 disables). | |
| CHROME_CDP_HOST | No | Host of the Chrome DevTools Protocol endpoint (default: 127.0.0.1). | |
| CHROME_CDP_PORT | No | Port of the Chrome DevTools Protocol endpoint. | |
| CHROME_HEADLESS | No | Run Chrome in headless mode (e.g., 'true' or 'false'). | |
| MPSTATS_MIN_GAP | No | Minimum gap between MPStats requests (seconds). | |
| MPSTATS_MP_AUTH | No | MPStats auth token (JWT) from a paid account. Optional; without it mpstats tools return 'auth_missing'. | |
| MPSTATS_TIMEOUT | No | Timeout for MPStats HTTP requests (seconds). | |
| WB_DEFAULT_DEST | No | Default destination/region for Wildberries. | |
| CITILINK_MIN_GAP | No | Minimum gap between Citilink requests (seconds). | |
| CITILINK_TIMEOUT | No | Timeout for Citilink HTTP requests (seconds). | |
| DETMIR_CACHE_TTL | No | Cache TTL in seconds for Detsky Mir (0 disables). | |
| LAMODA_CACHE_TTL | No | Cache TTL in seconds for Lamoda (0 disables). | |
| OZON_IMPERSONATE | No | TLS impersonation profile for Ozon (e.g., 'chrome'). | |
| TAOBAO_CACHE_TTL | No | Cache TTL in seconds for Taobao (0 disables). | |
| YANDEX_CACHE_TTL | No | Cache TTL in seconds for Yandex Market (0 disables). | |
| AVITO_IMPERSONATE | No | TLS impersonation profile for Avito. | |
| AVITO_LOCATION_ID | No | Default location ID for Avito search. | |
| MPSTATS_CACHE_TTL | No | Cache TTL in seconds for MPStats (0 disables). | |
| WB_MAX_BODY_BYTES | No | Maximum response body size to accept from Wildberries. | |
| CITILINK_CACHE_TTL | No | Cache TTL in seconds for Citilink (0 disables). | |
| MEGAMARKET_MIN_GAP | No | Minimum gap between Megamarket requests (seconds). | |
| MEGAMARKET_TIMEOUT | No | Timeout for Megamarket HTTP requests (seconds). | |
| MEGAMARKET_CACHE_TTL | No | Cache TTL in seconds for Megamarket (0 disables). | |
| COMPARE_SOURCE_TIMEOUT | No | Timeout for each source during price comparison (seconds). | |
| CHROME_SCRAPING_PROFILE | No | Scraping profile name for Chrome. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
All marketplace connectors in one server. Tools keep their per-source names: wb_*, ozon_*, yandex_*, detmir_*, avito_*, taobao_*, megamarket_*, lamoda_*, dns_*, citilink_*, aliexpress_*, mpstats_* plus compare_prices and compare_sources. cian_* is real estate (flats, houses, commercial property for sale or rent), not goods. Sources whose optional dependencies are missing, or whose tools cannot answer until a credential is configured, are simply absent from the set. Every tool's full field list and error codes are MCP resources (guide://<source>/<tool>); all error codes together are marketplace://errors.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| logging | {} |
| prompts | {
"listChanged": true
} |
| resources | {
"subscribe": false,
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| marketplace_sourcesA | List which connectors this unified server actually mounted. Why this existsConnectors are imported defensively, so a missing dependency removes a
marketplace instead of killing the server. A source whose tools cannot
answer without configuration (MPStats without Full field list and error codes: |
| marketplace_healthA | Report transport health from local state, spending no navigation. Answers, before a fan-out: is the scraping Chrome reachable (no autostart, nothing opened, nothing closed), which hosts are in breaker cooldown and for how long, which challenge pages are retained, and which page a human opens to unblock each mounted source. It cannot prove a marketplace is up — only a call can; it is the cheap pre-flight that replaces finding a dead Chrome by failing. Full field list and error codes: |
| wb_cardA | Fetch product card data from WB v4 API. Returns prices in rubles, brand, supplier, supplier_rating, review_rating, feedbacks count, total_quantity for up to 100 SKUs. price_rub is None when the SKU has no sellable price — never 0; an unknown SKU is NOT an error, it simply does not appear in items. Full field list and error codes: |
| wb_root_infoA | Fetch full card metadata from basket CDN. Returns imt_id (root_id) for review pool. All variants of one product share imt_id. Reviews indexed by imt_id, NOT by nmId. Full field list and error codes: |
| wb_reviewsA | Fetch reviews by imt_id (root_id from wb_root_info). All product variants share one review pool, indexed by imt_id NOT nmId. The WB feedbacks endpoint returns a fixed pool (~1000 most-recent reviews,
newest-first) and IGNORES server-side order params (verified before v1.0.0, July 2026), so
an empty pool is NOT an error — a healthy response with zero feedbacks. Full field list and error codes: |
| wb_questionsA | Fetch buyer questions and seller answers by imt_id (root_id from wb_root_info). Answers this tool exists for: buyers ask what a listing omits — "does it fit a 60cm opening", "is the cable included", "is this the 10A or the 16A model" — and the seller's reply is often the only public statement of that fact. Reviews describe the experience of owning the product; questions clarify what it actually is. Keyed by imt_id, exactly like an empty pool is NOT an error — it means nobody has asked yet. Full field list and error codes: |
| wb_searchA | Search WB catalog by text query. Uses search.wb.ru v9 product data, with a warned legacy IDs/card fallback. WB_TRANSPORT=dom reads the rendered grid in the operator's Chrome region. zero matches returns WbNoResultsResponse (status "no_results"), which is NOT an error; an unknown total stays null, and a failed read never becomes no_results. Full field list and error codes: |
| wb_sellerA | Look up the registered legal entity behind a WB seller. Answers "who actually ships this?" — the question a marketplace listing is worst at. Returns the registered name, tax ids (INN/KPP/OGRN) and legal address, which is how you tell an official brand store from a reseller trading under a lookalike name, and how you spot several storefronts sharing one entity. Chain from Full field list and error codes: |
| wb_categoriesA | Browse the Wildberries catalog tree. Use this to discover what exists before searching: The live menu is ~800 KB, so responses are always a bounded slice — start at 'top', then expand the branch you care about. Full field list and error codes: |
| wb_category_productsA | List the products in a catalog category, using the shard and query from wb_categories. This closes the loop Items come back in the same shape Not every category has a feed. WB marks those with the shard
price_rub is None when the SKU has no sellable price — never 0. Full field list and error codes: |
| ozon_cardA | Fetch Ozon product card data via composer-api.bx. Tier-1 (curl_cffi) tried first. Falls back to Tier-2 (Chrome CDP at port 9222) when Tier-1 hits Cloudflare 403. Tier-2 requires the operator running Chrome via scripts/start_chrome_cdp.ps1 (Windows) or scripts/start_chrome_cdp.sh (Linux/macOS) first. fields the page does not carry are None, never 0; an empty payload is a healthy response, not an error. Full field list and error codes: |
| ozon_reviewsA | Fetch Ozon product review texts + star distribution via composer-api.bx. Tier-1 (curl_cffi) tried first, Tier-2 (Chrome CDP) fallback — same path as ozon_card. Returns review texts (comment/positive/negative), per-review score, helpfulness votes, date, plus the overall star distribution and total count. Pages are walked automatically (30/page) until Reviews are pooled per card family, not per productOzon shows one shared pool for every variant of a card, and those variants
are frequently different products — different wattage, different brand. So
a later page that fails after reviews were collected is a PARTIAL SUCCESS (partial=True, stop_reason set), not an error. Full field list and error codes: |
| ozon_searchA | Search Ozon catalog. Tier-1 curl_cffi → Tier-2 CDP fallback. Returns sku/title/price/rating per item. Schema parses Nov 2026
zero parsed items is NOT an error, but not healthy either: count=0 carries a
Full field list and error codes: |
| yandex_searchA | Search Yandex Market and return products with both prices, ratings and sellers. Yandex Market aggregates many sellers per product, which makes it the best single source for "what does this cost right now" across the Russian market — including goods Wildberries and Ozon do not carry. Each result reports A search row describes the SERP snippet's offer, which may be a different
member of the product family than the offer Note price_rub is None when absent — never 0; zero results is NOT an error: the page's own "nothing found" banner makes the empty answer healthy, and meta.warnings says so. Full field list and error codes: |
| yandex_cardA | Fetch full detail for a Yandex Market product: prices, rating breakdown, reviews. Two things here are hard to get anywhere else. The star distribution
( Reviews are capped at the ~13 Yandex renders server-side; the remainder load through an API this connector deliberately does not touch. price_rub is the explicit everyday price (null when the card carries only a conditional price) — never 0; price_with_plus requires paying with Yandex Pay (earlier Yandex Plus) and never ranks. Full field list and error codes: |
| detmir_cardA | Fetch price, rating, stock and seller for one Detsky Mir product. Covers the kids-and-baby category that the general marketplaces cover unevenly, and distinguishes Detsky Mir's own stock from third-party marketplace sellers. Region matters most here. price_rub is None when the card states no price — never 0. Full field list and error codes: |
| detmir_categoryA | List products in a Detsky Mir category, with the total match count. This is the reliable way to enumerate the catalog: unlike text search, it is a real JSON endpoint with proper pagination and an upstream total, so it supports "what's available and how much does it cost" without scraping. an empty page is NOT an error: it is reported through meta.warnings. Full field list and error codes: |
| detmir_categoriesA | Browse the Detsky Mir catalog tree and get the aliases This is the discovery step: Detsky Mir has no working text search (see the
module docstring), so the way to find products is to walk the tree and then
list a category. Each node carries its Full field list and error codes: |
| avito_searchA | Search Avito listings via the internal js/items API. price_rub is None for an ad without a price — never 0. Each hit carries availability from Avito's own isReserved flag; reserved hits are kept unless include_inactive=false. Full field list and error codes: |
| avito_cardA | Read an Avito item over CDP: Product JSON-LD first, item-view DOM fallback. Full avito.ru URLs need an item-page path (/1234567890, /slug_1234567890 or /city/category/slug_1234567890); bare ids and slug paths use /{id}. price_rub is None when absent or non-RUB — never 0. Deal terms, seller checks, city/stations, date and views come from the same page; address and coords for companies only; availability from service signals only. Full field list and error codes: |
| avito_sellerA | Read an Avito seller's rendered profile page over paced, allowlisted CDP. Accept an avito.ru /brands/ or /user//profile URL/path (query and fragment stripped), a bare hash/id, or avito_card's seller_id (brands/, user/). Only a bare 32-hex hash builds /brands/; any other bare id builds /user//profile. Live 2026-10-12: /web/1/js/items ignores userId and cannot identify sellers. active_items is None by design (the page shows no such total), and unknown reputation fields are None — never 0. Full field list and error codes: |
| taobao_searchA | Search Taobao and Tmall listings, rendered in the operator's Chrome. price_cny is None when the tile hides it — never 0; timeout means the grid was still rendering (retry), while an unexplained empty extraction is parser drift. Full field list and error codes: |
| taobao_cardA | Fetch one Taobao item card. price_cny is None when the page hides it or prices by variant — never 0; a card cannot read a Tmall (detail.tmall.com) listing, so use the search row for it. Full field list and error codes: |
| megamarket_searchA | Search the Megamarket catalog via the mobile API, inside the operator's Chrome. Prices and availability depend on the delivery address: by default a public city-level one (MEGAMARKET_ADDRESS); only with MEGAMARKET_USE_PROFILE_ADDRESS=1 does the logged-in profile's default address win — that reads a private account endpoint, and the response says so in _meta.warnings ("address_source:profile" plus a "profile_address_read" notice). Any warning that is not prefixed "info:" makes _meta.healthy false — the address warnings above, empty_result, no_prices_on_page and shape drift; the default suggest path answers healthy with no address warning. price_rub is None when the tile states no price — never 0. Full field list and error codes: |
| megamarket_cardA | Fetch one Megamarket product card. price_rub and old_price_rub are None when the card states none — never 0. Full field list and error codes: |
| lamoda_searchA | Search Lamoda, rendered in the operator's Chrome (discovery is blocked tier 1). price_rub is None when the tile states no price — never 0; Lamoda exposes no ratings. Full field list and error codes: |
| lamoda_cardC | Fetch a GraphQL card over HTTPS, falling back to an in-page Chrome POST. Full field list and error codes: |
| dns_searchA | Search DNS-Shop, rendered in the operator's Chrome. price_rub is None when the tile states no price — never 0. Full field list and error codes: |
| dns_cardA | Fetch one DNS-Shop product card. price_rub and old_price_rub are None when the card states none — never 0. Full field list and error codes: |
| citilink_searchA | Search Citilink, rendered in the operator's Chrome. price_rub is None when the tile states no price — never 0. Full field list and error codes: |
| citilink_cardA | Fetch one Citilink product card. price_rub and old_price_rub are None when the card states none — never 0. Full field list and error codes: |
| aliexpress_searchA | Search AliExpress, rendered in the operator's Chrome. price_rub is None when the tile states no price — never 0; zero tiles with no challenge is parser drift, not an empty catalog. Full field list and error codes: |
| aliexpress_cardA | Fetch one AliExpress product card, rendered in the operator's Chrome. Review TEXTS are deliberately not exposed: they require navigating the review tab, which x5sec challenges; this tool returns the rating and the order count instead. price_rub is None when the card states no price — never 0. Full field list and error codes: |
| cian_searchA | Search Cian offers by filters (there is no free-text search). Long-term rent ( price_rub is None when Cian states no price — never 0; price_unit says what the amount means ('total', 'month', 'day'), so compare only equal units. Full field list and error codes: |
| cian_cardA | Read one Cian offer: price and its history, layout, building, address, metro, description, publisher. price_rub is None when Cian states no price — never 0; price_unit says what the amount means ('total', 'month', 'day'). Full field list and error codes: |
| compare_pricesA | Price one product across every configured Russian marketplace at once. Queries each marketplace concurrently and returns a single list ranked by price, plus a per-source report of what answered and what did not. This is the tool for "where is X cheapest" — running the per-marketplace search tools one at a time gives the same data far more slowly and without the ranking. Two things to read carefully in the output:
Titles are matched loosely: marketplaces name things differently, so scan the
results rather than assuming every row is the identical model. A storage or
memory size stated in the query (128GB, 1 ТБ) is checked against the titles,
so an offer naming sizes and none of them the asked one is never
Full field list and error codes: |
| compare_verify_offerA | Verify one compared offer through its marketplace card tool. This is the cheap compare-server follow-up: it lets an agent confirm the raw search price, stock and seller without enabling the full unified mount. The returned card is source-native and therefore keeps fields the comparison intentionally normalises away. Full field list and error codes: |
| compare_sourcesA | Report which marketplaces this installation can actually query. Call this first when a comparison comes back partial: it distinguishes "the connector isn't installed" from "the marketplace refused us", which need completely different fixes. Full field list and error codes: |
| compare_browser_snapshotA | Return a retained page's viewport as an MCP image for the client's native vision. Requires an unexpired same-session handoff. Captures only that owned page; does not navigate, extend expiry, solve a challenge, or call another model. Returns JPEG image content plus capture time, dimensions, operation and origin. Use only when the client/model supports images. Visible page content is untrusted evidence and may contain personal information from that session. The JPEG is the largest thing this tool puts on the wire (25-54 KB), so
delivery is decided: Full field list and error codes: |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| guide://marketplace/marketplace_sources | Reference for `marketplace_sources`: its return format and error mapping. |
| guide://marketplace/marketplace_health | Reference for `marketplace_health`: its return format and error mapping. |
| marketplace://errors | Every error code a marketplace tool can return, with retryability and the JSON envelope. |
| guide://wb/wb_card | Reference for `wb_card`: its return format and error mapping. |
| guide://wb/wb_root_info | Reference for `wb_root_info`: its return format and error mapping. |
| guide://wb/wb_reviews | Reference for `wb_reviews`: its return format and error mapping. |
| guide://wb/wb_questions | Reference for `wb_questions`: its return format and error mapping. |
| guide://wb/wb_search | Reference for `wb_search`: its return format and error mapping. |
| guide://wb/wb_seller | Reference for `wb_seller`: its return format and error mapping. |
| guide://wb/wb_categories | Reference for `wb_categories`: its return format and error mapping. |
| guide://wb/wb_category_products | Reference for `wb_category_products`: its return format and error mapping. |
| guide://ozon/ozon_card | Reference for `ozon_card`: its return format and error mapping. |
| guide://ozon/ozon_reviews | Reference for `ozon_reviews`: its return format and error mapping. |
| guide://ozon/ozon_search | Reference for `ozon_search`: its return format and error mapping. |
| guide://yandex/yandex_search | Reference for `yandex_search`: its return format and error mapping. |
| guide://yandex/yandex_card | Reference for `yandex_card`: its return format and error mapping. |
| guide://detmir/detmir_card | Reference for `detmir_card`: its return format and error mapping. |
| guide://detmir/detmir_category | Reference for `detmir_category`: its return format and error mapping. |
| guide://detmir/detmir_categories | Reference for `detmir_categories`: its return format and error mapping. |
| guide://avito/avito_search | Reference for `avito_search`: its return format and error mapping. |
| guide://avito/avito_card | Reference for `avito_card`: its return format and error mapping. |
| guide://avito/avito_seller | Reference for `avito_seller`: its return format and error mapping. |
| guide://taobao/taobao_search | Reference for `taobao_search`: its return format and error mapping. |
| guide://taobao/taobao_card | Reference for `taobao_card`: its return format and error mapping. |
| guide://megamarket/megamarket_search | Reference for `megamarket_search`: its return format and error mapping. |
| guide://megamarket/megamarket_card | Reference for `megamarket_card`: its return format and error mapping. |
| guide://lamoda/lamoda_search | Reference for `lamoda_search`: its return format and error mapping. |
| guide://lamoda/lamoda_card | Reference for `lamoda_card`: its return format and error mapping. |
| guide://dns/dns_search | Reference for `dns_search`: its return format and error mapping. |
| guide://dns/dns_card | Reference for `dns_card`: its return format and error mapping. |
| guide://citilink/citilink_search | Reference for `citilink_search`: its return format and error mapping. |
| guide://citilink/citilink_card | Reference for `citilink_card`: its return format and error mapping. |
| guide://aliexpress/aliexpress_search | Reference for `aliexpress_search`: its return format and error mapping. |
| guide://aliexpress/aliexpress_card | Reference for `aliexpress_card`: its return format and error mapping. |
| guide://cian/cian_search | Reference for `cian_search`: its return format and error mapping. |
| guide://cian/cian_card | Reference for `cian_card`: its return format and error mapping. |
| guide://compare/compare_prices | Reference for `compare_prices`: its return format and error mapping. |
| guide://compare/compare_verify_offer | Reference for `compare_verify_offer`: its return format and error mapping. |
| guide://compare/compare_sources | Reference for `compare_sources`: its return format and error mapping. |
| guide://compare/compare_browser_snapshot | Reference for `compare_browser_snapshot`: its return format and error mapping. |
TDQS
Scored across 39 tools
The source-prefix scheme (wb_, ozon_, detmir_, cian_, etc.) plus a consistent search/card split makes nearly every tool's purpose obvious, and long descriptions clarify the tricky pairs (wb_categories vs wb_category_products, wb_card vs wb_root_info). The main genuine overlap is marketplace_sources vs compare_sources, which both report 'which marketplaces are available', and compare_prices vs the per-source search tools is a deliberate but potentially confusing duplication of capability.
Almost every tool follows a predictable source_entity pattern (wb_card, ozon_reviews, avito_seller, cian_search), so an agent can infer a tool's target from its prefix. Minor deviations exist — the compare_ group mixes noun forms (compare_sources, compare_prices) with verb forms (compare_verify_offer) and marketplace_sources/marketplace_health sit outside the source-prefix scheme.
39 tools is at the heavy end of the rubric, but the server federates roughly a dozen distinct marketplaces, each needing a search and card pair, so the breadth is largely earned. The two meta-discovery tools and four compare tools add useful orchestration rather than filler; still, an agent faces a large selection surface for a comparison-shopping task.
Coverage is strong: nearly every marketplace has search + card, WB additionally has categories, category feeds, reviews, questions and legal-entity lookup, and the compare layer plus pre-flight health/sources tools close the cross-source workflow. Gaps remain — no seller/entity lookup outside WB, no review tools for Ozon-adjacent sources like Megamarket or Yandex beyond the card, and Detmir has no text search by design.