ozon-mcp
Provides integration with Ozon Seller & Performance APIs, enabling AI agents to access 466 API methods, execute calls with safety guards, perform automatic pagination, and run 13 ready-to-use analytical workflows for seller scenarios.
ozon-mcp
MCP server for the Ozon Seller & Performance APIs. Connect any AI agent to your Ozon cabinet in minutes.
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
uvpackage manager — install withcurl -LsSf https://astral.sh/uv/install.sh | shOzon 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 syncVerify it works
uv run ozon-mcp --helpYou should see the FastMCP usage line. The server speaks the MCP stdio protocol — point any compatible client at it (instructions below).
Related MCP server: wildberries-mcp
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-mcpOr 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_allwithoperation_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_analysisworkflow 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_checkworkflow.
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 |
| Execute any Ozon API method with safety + subscription guards |
| Auto-paginate — get every page, not just the first |
| Full docs for a method: schema, examples, rate limit, quirks |
| BM25 search across 466 methods (Russian or English, with stemming) |
| Browse the API by section |
| All methods inside one section |
| List ready-made analytical workflows (filterable by category) |
| Full step-by-step plan for one workflow |
| Methods that work well together (auto-extracted graph) |
| Curated request/response examples for a method |
| Per-method, per-section, or all |
| Read your current cabinet's subscription tier |
| What you unlock on a given tier |
| Check that bundled API specs are still fresh |
| 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 |
| analytics | Find products about to go out of stock |
| health | Check all seller-rating metrics in one shot |
| content | Find low-content-rating cards + actionable attributes |
| pricing | Find products with non-competitive pricing |
| warehouse | Per-warehouse stock breakdown for FBO |
| catalog | Full product catalog snapshot |
| orders | Incremental FBO order sync |
| orders | Incremental FBS / rFBS order sync |
| finance | Finance transactions for unit economics |
| analytics | Daily revenue / orders time series |
| advertising | Performance API ads catalog |
| warehouse | FBS warehouse stocks |
| 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/stocksis 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-missingSee CONTRIBUTING.md for how to add knowledge (workflows, examples, quirks, subscription overrides).
License
Available Tools
15 toolsozon_call_methodA
Execute a real call against the Ozon API.
SAFETY MODEL — read methods just work; write/destructive methods
require explicit confirmation flags. Each method's safety class is
visible in ozon_describe_method (safety field).
safety="read": no flag needed
safety="write": requires confirm_write=True
safety="destructive": requires BOTH confirm_write=True AND i_understand_this_modifies_data=True
SUBSCRIPTION GATE — when the method requires a higher tariff than the current cabinet tier, the call is refused locally and no HTTP request is sent. Saves quota on calls that would 403 anyway.
RATE LIMITS — 429 responses are retried up to MAX_RETRIES times honouring Retry-After. Slow endpoints (e.g. /v1/analytics/turnover/ stocks at 1 req/min) are serialised via a per-process semaphore.
On any failure returns a structured OzonError envelope —
agents should inspect error_type and decide.
Args: operation_id: e.g. "FinanceAPI_FinanceTransactionListV3" params: request body matching the method's request_schema confirm_write: required when method.safety == "write" or "destructive" i_understand_this_modifies_data: extra confirmation for destructive cabinet_tier: override the cached cabinet tier (e.g. "PREMIUM_PLUS")
Inputs: operation_id (required), params, cabinet_tier, confirm_write, +1 more. Returns: object
ozon_describe_methodA
Get a complete description of one Ozon API method.
Returns the method's metadata plus fully-resolved JSON Schema for request and responses. All $ref pointers are inlined; oneOf/anyOf/allOf combinators are preserved verbatim. When knowledge layer is loaded, also includes rate_limit, quirks, examples, and related methods — everything an agent needs to call the method correctly.
Provide either operation_id (preferred) OR path (+ optional http_method).
Inputs: path, http_method, operation_id. Returns: object
ozon_fetch_allA
Fetch all pages of a paginated Ozon endpoint.
Walks the endpoint's pagination pattern (offset/page/last_id/cursor/
page_token — see knowledge/pagination_patterns.yaml) until the
endpoint reports the last page or max_items is reached. Per-page
rate limits are still enforced via the same machinery as
ozon_call_method.
Args: operation_id: same as ozon_call_method, must support pagination params: request body WITHOUT offset/limit/last_id/cursor — the paginator owns those fields max_items: safety cap, range [1, MAX_FETCH_ALL_ITEMS] cabinet_tier: override the cached cabinet tier
Returns:
{"items": [...], "total_fetched": N, "truncated": bool, "pages_fetched": int} on success or a structured OzonError
on failure.
Inputs: operation_id (required), params, max_items, cabinet_tier. Returns: object
ozon_get_error_catalogA
Look up Ozon API errors and their solutions.
Without arguments returns all known errors. With code (e.g. "429" or "InvalidArgument") filters by code. With operation_id returns errors specific to that method plus all generic ones.
Inputs: code, operation_id. Returns: object
ozon_get_examplesB
Get hand-crafted request examples for one method.
Examples are real, validated payloads matching the method's request schema — copy them as starting points for your own calls.
Inputs: operation_id (required). Returns: object
ozon_get_rate_limitsA
Look up rate limits for a method, section, or the whole API.
Without arguments returns all known limits. With operation_id, returns the most specific limit (per-method overrides per-section overrides global).
NOTE: Many limits in v0.2 are conservative guesses (source: 'guess'). Verify against real Ozon responses before relying on them in production.
Inputs: section, operation_id. Returns: object
ozon_get_sectionA
List all methods inside a section (by section name or tag).
Args: query: section name or tag, e.g. "FinanceAPI", "Финансовые отчёты", "ProductAPI"
Inputs: query (required). Returns: object
ozon_get_subscription_statusA
Get the current account's subscription tier from /v1/seller/info.
Returns the subscription type, the is_premium flag, plus the list
of all Ozon API methods that might require this exact tier.
Result is cached per server process; pass refresh=True to
bypass the cache. Errors are NEVER cached.
Available only when seller credentials are configured.
Inputs: refresh. Returns: object
ozon_get_swagger_metaA
Return metadata about the bundled Ozon swagger snapshots.
Tells the caller which spec version we are shipping, how many methods it contains, when the snapshot was refreshed, and the SHA-256 of the file. Useful for:
agents that need to decide whether to re-check docs online;
operators validating that a refresh actually landed;
bug reports — include this in the issue so reproduction is exact.
Returns {"error": "missing"} when the package was built without
swagger_meta.json (pre-v0.6 snapshot).
Inputs: no named parameters. Returns: object
ozon_get_workflowA
Get the full step-by-step plan for one workflow.
Returns ordered steps with operation_ids, pagination/batching/concurrency
guidance, recommended DB schema, and known gotchas. Analytical
workflows additionally carry interpret (how to read the data),
when_to_use (situations the workflow fits) and common_mistakes.
Args: name: workflow name from ozon_list_workflows, e.g. "sync_orders_fbs" or "oos_risk_analysis"
Inputs: name (required). Returns: object
ozon_list_methods_for_subscriptionA
List all Ozon methods that mention a specific subscription tier.
Useful when an agent wants to know "what extra capabilities do I unlock by upgrading to Premium Plus?" or "which methods will fail without Premium?". Tiers are auto-extracted from method documentation, so this is a hint, not a contract — the actual hard 403 set may differ.
Args: tier: one of UNSPECIFIED, PREMIUM_LITE, PREMIUM, PREMIUM_PLUS, PREMIUM_PRO
Inputs: tier (required). Returns: object
ozon_list_sectionsA
List all Ozon API sections (Seller + Performance) with method counts.
Use this first to orient yourself in the API. Returns sections grouped by api ('seller' or 'performance'), each with the human-readable section name, the underlying tag, and the number of methods inside.
Inputs: no named parameters. Returns: object
ozon_list_workflowsA
List all curated workflows, optionally filtered by category.
Workflows are step-by-step recipes for chaining Ozon API methods into
real data pipelines or analytical reports. Use ozon_get_workflow
to fetch the full plan for a specific workflow.
Args:
category: optional filter — one of "catalog", "orders",
"analytics", "health", "pricing", "content", "advertising",
"warehouse", "returns", "finance". When provided, only
workflows in that category are returned. categories in
the response always lists every value present in the catalogue.
Inputs: category. Returns: object
ozon_search_methodsA
Full-text search across all Ozon API methods.
Searches over operation_id, path, summary, description, section, and tag using BM25 ranking with field boosting (summary x4, path/op_id x3, description x1). Supports Russian and English queries with stemming.
Args: query: free-text query, e.g. "list of postings" or "финансовые транзакции" section: optional filter — match by section name or tag (case-insensitive substring) api: optional filter — "seller" or "performance" safety: optional filter — "read", "write", or "destructive" limit: max results to return (default 10)
Inputs: query (required), api, limit, safety, +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Most tools are clearly distinct: listing sections, searching methods, describing methods, workflows, rate limits, errors, examples, and calling methods all have separate purposes. The only mild overlap is between ozon_list_sections and ozon_get_section (both navigate the API structure), but their roles are differentiated enough by description.
The tools follow a consistent ozon_verb_noun pattern (list_sections, search_methods, describe_method, get_section, get_related_methods, list_workflows, get_workflow, get_rate_limits, get_error_catalog, get_examples, get_swagger_meta, list_methods_for_subscription, get_subscription_status, call_method, fetch_all). Minor deviation: ozon_fetch_all uses a verb+adverb instead of verb_noun, and ozon_call_method is a generic verb rather than a resource-specific one, but the pattern is otherwise highly predictable.
15 tools is well-scoped for an Ozon API MCP server that needs to cover discovery, documentation, workflows, rate limits, errors, examples, and execution. Each tool serves a distinct function in the API exploration and calling lifecycle, and none feel redundant.
The server covers the full API interaction lifecycle: orientation (list_sections), search (search_methods), deep documentation (describe_method), related methods, curated workflows, rate limits, errors, examples, subscription gating, direct calling, and pagination. There are no obvious dead ends—an agent can discover, understand, and execute any Ozon API method.
Maintenance
Related MCP Connectors
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Hosted Amazon Seller Central and Amazon Ads MCP server for Claude, ChatGPT, Cursor, and agents.
Related MCP Servers
- AlicenseAqualityBmaintenanceUniversal MCP server for the Avito API (Russia's largest classifieds marketplace), built for autonomous AI agents to operate an account hands-free — 145 tools across 18 domains (listings, messenger, orders, delivery, promotion, autoload, reviews, analytics). Safe-by-default: dry-run, idempotency, structured errors, confirmation flow.144196 npm26MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that turns Wildberries marketplace into a toolkit for LLM agents, enabling product search, detailed card inspection, price history, reviews, and cross-product comparison.-
- AlicenseNot gradedqualityBmaintenanceMCP server for Ozon sellers with a built-in Chinese operations knowledge base and 466 API methods, enabling AI agents to discover, understand, and execute Ozon Seller and Performance API operations safely and efficiently.1MIT
- AlicenseAqualityDmaintenanceA knowledge-based MCP server for Ozon sellers, enabling AI agents to search a 42-lesson Chinese operations playbook and discover/call over 460 Seller and Performance API methods for real business actions.155MIT