PCDCK/ozon-mcp

MCP server for the Ozon Seller & Performance APIs. Connect any AI agent to your Ozon cabinet in minutes.

CI

ozon-mcp is a knowledge-rich MCP server that turns the entire Ozon seller toolkit into 15 high-leverage tools. AI agents (Claude, Cursor, Cline, Continue, Goose, Zed, …) can search the API in Russian or English, drill into any of 466 methods with a fully-resolved JSON Schema, and execute calls with built-in safety guards. Subscription- aware, automatic pagination over all 4 cursor styles, retry/back-off on 429s, and 13 ready-to-use analytical workflows.

Key facts: 466 indexed methods (420 Seller + 46 Performance), 55 sections, 5 subscription tiers modelled, 38 paginated endpoints auto-walked, 43 destructive methods double-gated, 13 curated workflows for typical seller scenarios.

---

Quick start

Prerequisites

• Python 3.12 or 3.13
• uv package manager — install with curl -LsSf https://astral.sh/uv/install.sh | sh
• Ozon Seller API credentials (Client-Id + Api-Key) — get them at https://seller.ozon.ru/app/settings/api-keys

Installation

git clone https://github.com/PCDCK/ozon-mcp.git
cd ozon-mcp
uv sync

Verify it works

uv run ozon-mcp --help

You should see the FastMCP usage line. The server speaks the MCP stdio protocol — point any compatible client at it (instructions below).

---

Connecting to your AI agent

ozon-mcp uses the standard MCP stdio transport. Every example below exposes the same 15 tools — pick whichever client you already use.

Claude Desktop

Edit: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

{
  "mcpServers": {
    "ozon": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ozon-mcp",
                "run", "ozon-mcp"],
      "env": {
        "OZON_CLIENT_ID": "your-seller-client-id",
        "OZON_API_KEY": "your-seller-api-key",
        "OZON_PERFORMANCE_CLIENT_ID": "your-perf-client-id",
        "OZON_PERFORMANCE_CLIENT_SECRET": "your-perf-secret"
      }
    }
  }
}

Claude Code (CLI)

cd /path/to/ozon-mcp
claude mcp add ozon -- uv run ozon-mcp

Or add to ~/.claude/mcp.json with the same shape as the Claude Desktop config above.

Cursor

Settings → MCP → Add new MCP Server, or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ozon": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ozon-mcp",
                "run", "ozon-mcp"]
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ozon": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ozon-mcp",
                "run", "ozon-mcp"]
    }
  }
}

Cline (VS Code extension)

Cline → Settings → MCP Servers → Add:

{
  "ozon": {
    "command": "uv",
    "args": ["--directory", "/absolute/path/to/ozon-mcp",
              "run", "ozon-mcp"]
  }
}

Continue.dev

Edit ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uv",
          "args": ["--directory", "/absolute/path/to/ozon-mcp",
                    "run", "ozon-mcp"]
        }
      }
    ]
  }
}

Goose, Zed, or any other MCP client

Any client that speaks MCP stdio will work. Generic config:

command: uv
args: ["--directory", "/absolute/path/to/ozon-mcp", "run", "ozon-mcp"]
transport: stdio
env:
  OZON_CLIENT_ID: ...
  OZON_API_KEY: ...

Browse the official MCP client list at https://modelcontextprotocol.io/clients.

---

Usage examples

All examples below show realistic responses copied from tests/fixtures/responses/ — anonymized identifiers (99000001, TEST-SKU-001) but real shape.

Example 1 — Get all your products

You: Use ozon_fetch_all with operation_id="ProductAPI_GetProductList" to get all my products.

The agent calls:

{
  "operation_id": "ProductAPI_GetProductList",
  "params": {"filter": {"visibility": "ALL"}},
  "max_items": 10000
}

Server walks the last_id cursor automatically and returns:

{
  "ok": true,
  "items": [
    {"product_id": 99000001, "offer_id": "TEST-SKU-001", "archived": false},
    {"product_id": 99000002, "offer_id": "TEST-SKU-002", "archived": false},
    {"product_id": 99000003, "offer_id": "TEST-SKU-003", "archived": true}
  ],
  "total_fetched": 3,
  "truncated": false,
  "pages_fetched": 1
}

Example 2 — Find products at risk of going out of stock

You: Run the oos_risk_analysis workflow for my cabinet.

Agent first inspects the workflow:

ozon_get_workflow({"name": "oos_risk_analysis"})

→ tells the agent to call AnalyticsAPI_StocksTurnover (rate-limited to 1 req/min — the server's per-endpoint queue handles that for you) and how to interpret turnover_grade. The call returns:

{
  "items": [
    {"sku": 99000001, "current_stock": 12, "ads": 1.5,
     "idc": 8.0, "turnover_grade": "DEFICIT",
     "turnover_grade_cluster": "DEFICIT_GROWING"},
    {"sku": 99000002, "current_stock": 25, "ads": 0.8,
     "idc": 31.25, "turnover_grade": "OPTIMAL",
     "turnover_grade_cluster": "OPTIMAL_FALLING"},
    {"sku": 99000003, "current_stock": 0, "ads": 0.0,
     "idc": 0.0, "turnover_grade": "NO_SALES",
     "turnover_grade_cluster": "NO_SALES"}
  ]
}

The workflow's interpret field tells the agent to flag SKUs where idc < 14 or turnover_grade ∈ {DEFICIT, NO_SALES} and surface them sorted by idc asc.

Example 3 — Full cabinet health check

You: Check the health of my Ozon cabinet using the cabinet_health_check workflow.

The workflow tells the agent to read three endpoints in parallel — RatingAPI_RatingSummaryV1, SellerAPI_SellerInfo, AverageDeliveryTimeSummary. The first call returns:

{
  "groups": [
    {
      "group_name": "Выполнение заказов",
      "items": [
        {"rating": "rating_on_time", "name": "Процент заказов вовремя",
         "current_value": 97.5, "status": "OK", "value_type": "PERCENT"},
        {"rating": "rating_review_avg_score", "name": "Средняя оценка",
         "current_value": 4.7, "status": "OK", "value_type": "RATING"}
      ]
    },
    {
      "group_name": "Качество сервиса",
      "items": [
        {"rating": "rating_price_index", "name": "Индекс цен",
         "current_value": 1.01, "status": "OK", "value_type": "INDEX"}
      ]
    }
  ],
  "premium_scores": [
    {"rating": "rating_on_time", "value": 97.5,
     "penalty_score_per_day": 0, "scope": "premium_plus"}
  ]
}

Example 4 — Analyze product pricing

You: Which of my products have a red price index?

Agent runs the pricing_analysis workflow and inspects the price_indexes.color_index field on every item:

{
  "product_id": 99000001, "offer_id": "TEST-SKU-001",
  "price": {"price": "399.0000", "marketing_seller_price": "399.0000",
             "min_price": "299.0000"},
  "price_indexes": {
    "color_index": "WITHOUT_INDEX",
    "ozon_index_data": {"minimal_price": "395.0000",
                          "price_index_value": 1.01}
  },
  "commissions": {"sales_percent_fbo": 0.13, "sales_percent_fbs": 0.13}
}

The workflow's common_mistakes list reminds the agent to compare against marketing_seller_price (the actual buyer-facing price), not just the base price.

Example 5 — Content audit

You: Find products with low content rating and tell me what to improve.

Agent runs content_audit, gets per-SKU ratings + the list of attributes that would lift the score:

{
  "products": [
    {
      "sku": 99000001, "rating": 85,
      "groups": [
        {"key": "media", "rating": 100},
        {"key": "characteristics", "rating": 75,
         "improve_attributes": [
           {"id": 4191, "name": "Цвет"},
           {"id": 8292, "name": "Материал"}
         ],
         "improve_at_least": 4}
      ]
    }
  ]
}

The workflow tells the agent that a +10 lift to rating measurably improves search ranking — so filling in those two attributes is worth ~4 points.

---

Available tools (15)

Tool	What it does
ozon_call_method	Execute any Ozon API method with safety + subscription guards
ozon_fetch_all	Auto-paginate — get every page, not just the first
ozon_describe_method	Full docs for a method: schema, examples, rate limit, quirks
ozon_search_methods	BM25 search across 466 methods (Russian or English, with stemming)
ozon_list_sections	Browse the API by section
ozon_get_section	All methods inside one section
ozon_list_workflows	List ready-made analytical workflows (filterable by category)
ozon_get_workflow	Full step-by-step plan for one workflow
ozon_get_related_methods	Methods that work well together (auto-extracted graph)
ozon_get_examples	Curated request/response examples for a method
ozon_get_rate_limits	Per-method, per-section, or all
ozon_get_subscription_status	Read your current cabinet's subscription tier
ozon_list_methods_for_subscription	What you unlock on a given tier
ozon_get_swagger_meta	Check that bundled API specs are still fresh
ozon_get_error_catalog	Look up any Ozon error code

---

Ready-made workflows (13)

Workflows are curated step-by-step recipes. Use ozon_get_workflow("name") to fetch the full plan, including interpret, when_to_use, common_mistakes, and the recommended DB schema for sync-style workflows.

Workflow	Category	What it solves
oos_risk_analysis	analytics	Find products about to go out of stock
cabinet_health_check	health	Check all seller-rating metrics in one shot
content_audit	content	Find low-content-rating cards + actionable attributes
pricing_analysis	pricing	Find products with non-competitive pricing
warehouse_stock_distribution	warehouse	Per-warehouse stock breakdown for FBO
sync_products_catalog	catalog	Full product catalog snapshot
sync_orders_fbo	orders	Incremental FBO order sync
sync_orders_fbs	orders	Incremental FBS / rFBS order sync
sync_finance_transactions	finance	Finance transactions for unit economics
sync_analytics_daily	analytics	Daily revenue / orders time series
sync_advertising_campaigns	advertising	Performance API ads catalog
sync_warehouse_stocks	warehouse	FBS warehouse stocks
sync_returns_rfbs	returns	rFBS returns sync

---

API coverage

API	Methods	Sections
Ozon Seller API	420	49
Ozon Performance API	46	6
Total	466	55

Subscription tiers modelled (low → high): LITE → STANDARD → PREMIUM → PREMIUM_PLUS → PREMIUM_PRO.

---

Key features

Subscription-aware

The server knows which methods are gated on Premium tiers and refuses the call before it leaves your machine — saves your API quota:

{
  "error": "subscription_gate",
  "error_type": "subscription_gate",
  "code": 7,
  "message": "Endpoint requires PREMIUM_PRO, cabinet has PREMIUM_PLUS",
  "operation_id": "ProductPricesDetails",
  "required_tier": "PREMIUM_PRO",
  "cabinet_tier": "PREMIUM_PLUS",
  "retryable": false,
  "http_call_skipped": true
}

Rate-limit management

• Auto-retry with exponential back-off on 429.
• Honours Retry-After (both delta-seconds and RFC 7231 HTTP-date).
• Per-endpoint semaphore for slow methods (e.g. /v1/analytics/turnover/stocks is hard-limited to 1 req/min on the Ozon side — the server queues parallel calls automatically).

Auto-pagination

ozon_fetch_all handles all four pagination patterns Ozon uses: offset/limit, cursor, last_id, page_number. It also detects the rare case where the server returns the same cursor twice in a row and breaks the loop instead of spinning forever.

ozon_fetch_all(
  operation_id="ProductAPI_GetProductList",
  params={"filter": {"visibility": "ALL"}},
  max_items=10_000,
)
# → {"items": [...all products...], "total_fetched": 847,
#    "truncated": false, "pages_fetched": 1}

Unified error envelope

Every tool that can fail returns the same shape — easy to branch on in any agent or downstream code:

{
  "error": "rate_limit_exceeded",
  "error_type": "rate_limit | subscription_gate | not_found | invalid_params | server_error | timeout | auth | forbidden | conflict | ...",
  "message": "Human-readable explanation",
  "code": 429,
  "operation_id": "AnalyticsAPI_StocksTurnover",
  "endpoint": "/v1/analytics/turnover/stocks",
  "retryable": true,
  "retry_after_seconds": 60
}

Safety classification baked into the catalog

Every method carries a safety field — read, write, or destructive. Write requires confirm_write=True; destructive requires both confirm_write=True AND i_understand_this_modifies_data=True. Heuristics from the schema extractor are reinforced by 43 curated safety_warning entries in quirks.yaml so the agent always sees a clear reminder before mutating anything.

---

Keeping the API specs up to date

Ozon refreshes their swagger periodically. To sync:

cd parser/                               # the parser repo / drop-zone
python parse_swagger.py                  # downloads + sanitises both APIs
cp seller_swagger.json ../src/ozon_mcp/data/
cp perf_swagger.json   ../src/ozon_mcp/data/
cp swagger_meta.json   ../src/ozon_mcp/data/

Run ozon_get_swagger_meta to confirm the bundled snapshot is fresh (the CI also fails the build when the snapshot is older than 14 days).

---

Development

git clone https://github.com/PCDCK/ozon-mcp.git
cd ozon-mcp
uv sync --extra dev

# Tests (≈25s, 274 currently)
uv run pytest tests/ --ignore=tests/live

# Code quality
uv run ruff check src tests
uv run mypy src/ozon_mcp

# Coverage
uv run pytest tests/ --ignore=tests/live --cov=src/ozon_mcp \
    --cov-report=term-missing

See CONTRIBUTING.md for how to add knowledge (workflows, examples, quirks, subscription overrides).

---

License

MIT