Skip to main content
Glama
YegorMy

marketplace-mcp

by YegorMy
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Marketplace MCP

Read in Russian: readme_rus.md

Marketplace MCP is a read-only MCP server for product search, review sampling, and price comparison across Ozon, Wildberries, Yandex Market, and Avito.

It is built for agents that need marketplace data without logging in, touching carts, or automating checkout. The server returns normalized product data, comparison groups, warnings, and source URLs. When a marketplace blocks scraping or shows anti-bot behavior, the tool reports that instead of trying to bypass it.

Tools

  • marketplaces_search searches one or more marketplaces.

  • ozon_search searches Ozon only.

  • wildberries_search searches Wildberries only.

  • yandex_market_search searches Yandex Market only.

  • avito_search searches Avito as an explicit used-market path.

  • marketplaces_compare searches retail marketplaces and groups similar products; Avito is opt-in with include_avito=true.

  • marketplaces_product_details reads a product page by URL.

  • marketplaces_product_reviews returns a compact review sample for supported marketplaces.

  • marketplaces_get_artifact reads a saved result artifact.

Returned product fields include marketplace, title, URL, image URL, price, old price, currency, rating, review count, availability, delivery notes, seller evidence, used-item condition and location, scraped timestamp, and warnings when data is partial.

Related MCP server: hermes-marketplace-tools

Safety model

Marketplace MCP is deliberately read-only.

By default it does not:

  • log in to a marketplace;

  • use cookies or account sessions;

  • add items to cart;

  • place orders;

  • reserve products;

  • submit payments;

  • bypass CAPTCHA or anti-bot systems.

Prices are scraped snapshots. Always open the product URL before making a purchase decision.

Marketplace MCP uses Hive Web as the default page loader (MARKETPLACES_WEB_BACKEND=hive_web). legacy mode keeps the previous Playwright/httpx loading stack. auto tries Hive Web first and falls back to legacy only if Hive Web is unavailable.

  • MARKETPLACES_WEB_BACKEND: hive_web (default), auto, legacy

  • MARKETPLACES_HIVE_WEB_MAX_TOKENS: maximum tokens for Hive Web text snapshot (default 12000)

  • MARKETPLACES_CAMOFOX_URL: optional Camofox base URL for anonymous ephemeral read-only fallback sessions.

  • MARKETPLACES_AVITO_REGION_SLUG: Avito region path (default all).

  • MARKETPLACES_AVITO_STATE_PATH: shared Avito rate-limit state file (default ~/.cache/marketplaces-mcp/avito-access-state.json).

  • MARKETPLACES_AVITO_MIN_INTERVAL_SECONDS: minimum interval between Avito live requests (default 10).

  • MARKETPLACES_AVITO_BLOCK_COOLDOWN_SECONDS: cooldown after an explicit Avito IP block (default 21600, six hours).

When rendered pages are unavailable, public search-index discovery may return canonical product links. Such results always have no verified price and include INDEX_DISCOVERY_ONLY and PRICE_UNVERIFIED; an index snippet is never treated as current marketplace data. Avito is excluded from default retail search and comparison because each used listing is a unique physical item.

Runtime settings can also live in ~/.config/marketplaces-mcp/config.json or in the path from MARKETPLACES_CONFIG:

{
  "web_backend": "hive_web",
  "hive_web_max_tokens": 12000,
  "browser_channel": "chrome",
  "browser_headless": true,
  "browser_locale": "ru-RU",
  "browser_timezone": "Europe/Moscow",
  "browser_args": ["--disable-blink-features=AutomationControlled"],
  "browser_default_user_agent": true,
  "proxies": {
    "ozon": "http://user:password@proxy.example:19081",
    "yandex_market": null
  }
}

For local development, scripts/camofox-bridge.py exposes the small Camofox-compatible read-only API used by the adapters (POST /tabs, GET /tabs/{tabId}/snapshot, DELETE /sessions/{userId}) on top of Hive Web/Playwright:

uv run python scripts/camofox-bridge.py --host 127.0.0.1 --port 8765 --headful

Then set "camofox_url": "http://127.0.0.1:8765" in the runtime config.

Per-marketplace proxy values are only applied to that marketplace. When a proxy is configured for a marketplace, the adapter skips Hive Web for that marketplace and uses the proxied Playwright/httpx path. Use an HTTP proxy with authentication for browser-heavy marketplaces because Chromium/Playwright does not support authenticated SOCKS5 proxies. Environment variables override file values: MARKETPLACES_PROXY_OZON_URL, MARKETPLACES_OZON_PROXY_URL, OZON_PROXY_URL, MARKETPLACES_PROXY_YANDEX_MARKET_URL, MARKETPLACES_YANDEX_MARKET_PROXY_URL, YANDEX_MARKET_PROXY_URL.

Ozon is rendered with JavaScript enabled. When an Ozon proxy is configured, the Ozon adapter keeps Playwright headful even if browser_headless is true, because Ozon is stricter in headless mode. Disabling JavaScript is not a useful fallback: Ozon returns an anti-bot challenge asking the browser to enable JavaScript, and the adapter reports it as CAPTCHA_OR_BLOCKED.

Requirements

  • Python 3.11+

  • uv

  • Hermes or another MCP client

Install

git clone https://github.com/YegorMy/marketplace-mcp.git
cd marketplace-mcp
uv sync

Run tests:

uv run pytest -q

Run the MCP smoke test:

uv run python scripts/test-mcp-client.py

Run a live search smoke test:

uv run python scripts/smoke-search.py --query "бумага a4" --limit 2

Run one explicit Avito canary without touching retail marketplaces:

uv run python scripts/live_canary.py --avito-only --avito-query "кроватка Stokke"

Live search depends on current marketplace behavior. Ozon and Yandex Market may rate-limit, block, or change page markup. In that case the smoke test should return warnings such as CAPTCHA_OR_BLOCKED instead of crashing.

Hermes setup

The installer writes a marketplaces MCP server entry into ~/.hermes/config.yaml and tests the connection:

bash scripts/install-hermes-mcp.sh

You can override the MCP server name:

SERVER_NAME=marketplaces bash scripts/install-hermes-mcp.sh

Manual Hermes config:

mcp_servers:
  marketplaces:
    command: /absolute/path/to/uv
    args: ["run", "--project", "/absolute/path/to/marketplace-mcp", "marketplaces-mcp"]
    connect_timeout: 60
    enabled: true

After changing MCP config, reload MCP in the client or start a new session.

Other MCP clients

Any MCP client that supports stdio can run the same command:

uv run --project /absolute/path/to/marketplace-mcp marketplaces-mcp

Claude Code:

claude mcp add -s user marketplaces -- uv run --project /absolute/path/to/marketplace-mcp marketplaces-mcp

Codex CLI:

codex mcp add marketplaces -- uv run --project /absolute/path/to/marketplace-mcp marketplaces-mcp

OpenCode uses the same stdio command in its MCP config:

{
  "mcp": {
    "marketplaces": {
      "command": "uv",
      "args": ["run", "--project", "/absolute/path/to/marketplace-mcp", "marketplaces-mcp"]
    }
  }
}

Development

uv sync
uv run pytest -q
uv run python scripts/test-mcp-client.py
uv run python scripts/smoke-search.py --query "бумага a4" --limit 2

The adapters live under src/marketplaces_mcp/adapters/. Tests use fixtures where possible so the core behavior does not depend on live marketplace pages.

License

MIT

Available Tools

6 tools
marketplaces_compareD
ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
strategyNoauto
limit_per_marketplaceNo

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

marketplaces_get_artifactD
ParametersJSON Schema
NameRequiredDescriptionDefault
nameNocontent.json
artifact_idYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

marketplaces_product_detailsD
ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
strategyNoauto

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv0.1.0
    • First observedmarketplaces_compare
    • First observedmarketplaces_get_artifact
    • First observedmarketplaces_product_details
    • First observedmarketplaces_search
    • First observedozon_search
    • First observedyandex_market_search
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

D1.6/5.0

Scored across 6 tools

Disambiguation3/5

Tools like marketplaces_search, ozon_search, and yandex_market_search overlap in purpose, making it unclear when to use which. marketplaces_compare and marketplaces_product_details also have unclear boundaries.

Naming Consistency2/5

Naming is inconsistent: some tools use 'marketplaces_' prefix while others use specific marketplace names (ozon_, yandex_market_). Verb usage varies (compare, get, details, search) without a clear pattern.

Tool Count4/5

With 6 tools, the count is appropriate for a focused marketplace server. It covers search, comparison, and details without being excessive.

Completeness3/5

The tool set covers search and product details but lacks obvious lifecycle operations like add, update, or delete products. The 'get_artifact' tool is ambiguous and doesn't clearly fit.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Yahoo! Shopping MCP

    ymuichiro
    A
    license
    A
    quality
    B
    maintenance
    Read-only MCP server for searching Yahoo! Shopping products through the Yahoo! Shopping Item Search API v3. It supports keyword and JAN-code search with price, stock, condition, shipping, sorting, category, brand, seller, image-size, and pagination filters.
    1
    1
    MIT

Appeared in Searches