OZON MCP

An open-source MCP Server for Ozon sellers, with a built-in 42-lesson Chinese operations knowledge base and 466 API methods, enabling AI Agents to search operations experience, call Seller/Performance APIs, and execute real business operations.

Table of Contents

• Project Overview

• Core Capabilities

• Use Cases

• System Architecture

• Project Structure

• Environment Requirements

• Quick Start

• Environment Variables

• MCP Client Configuration

• Usage Examples

• Development and Testing

• Security Notes

• FAQ

• License

• Disclaimer

Project Overview

OZON MCP is a knowledge-based MCP Server built on the Model Context Protocol. It wraps the complete API documentation, parameter schemas, rate-limit rules, and business workflows of the Ozon Seller API and Performance API into standardized MCP tools, allowing AI Agents such as Claude, Cursor, and Codex to directly search, understand, and call Ozon APIs.

What Problem Does It Solve

The Ozon open platform has two API sets (Seller + Performance), totaling over 460 endpoints distributed across 55 business modules. Manually browsing documentation, constructing requests, and handling pagination and rate limits is time-consuming.

OZON MCP turns an AI Agent into your Ozon operations assistant:

• Agents can search API methods in Chinese or Russian to find the endpoint they need

• Each method returns a fully parsed JSON Schema, including request parameters, response structure, rate limits, and known pitfalls

• Write operations are protected by multiple layers of safety guards to prevent accidental actions

• Supports automatic pagination for traversing large datasets

• Includes 13 curated business workflows covering stockout analysis, pricing diagnostics, store health checks, and more

Who Is It For

• Ozon sellers who want to use AI to assist with daily operations analysis

• Cross-border e-commerce tool developers who need to integrate Ozon capabilities into Agents

• Developers interested in the MCP protocol and real-world implementation patterns

Core Capabilities

API Discovery and Navigation

Business Workflows

13 curated workflows covering the following business categories:

Each workflow includes: a sequence of operation steps, pagination/concurrency guidance, recommended database schemas, known pitfalls, and result interpretation notes.

Safe Execution

Reference Information

Subscription Permissions

Note: The current version is a knowledge server — even without API credentials, all discovery, search, reference, and workflow tools work normally. Credentials are only needed when executing real API calls.

API Method Overview

The project includes a complete Chinese catalog of 466 Ozon API methods (methods_catalog.md), covering all areas of Ozon seller business:

Once connected, Agents can search in Chinese (e.g., "query order list", "batch update inventory"), and with the card-style Chinese descriptions in the catalog, quickly locate the correct API and execute calls. Each method is annotated with its HTTP method, endpoint path, security level, and subscription requirement, so Agents can directly determine whether write-operation confirmation or a higher subscription tier is needed.

Chinese Ozon Operations Knowledge Base

The project includes a complete Chinese Ozon operations knowledge base, compiled from 42 Ozon e-commerce lessons, containing 610 searchable knowledge chunks. Agents can search in natural Chinese to quickly locate operations experience, procedures, and pitfall-avoidance guides.

Knowledge Base Overview

Covered Topics

The knowledge base covers the full chain from store opening to after-sales for Ozon sellers:

• Platform business models (reselling, curated listing, mass listing, dropshipping)

• Four fulfillment models: FBS, FBO, FBP, rFBS

• Store registration and international shipping cost calculation

• Warehouse setup and logistics configuration

• Product selection methods and building a product selection pool

• Product weight and dimension verification

• Seller back-office module walkthrough

• Product card optimization and main image creation

• Pricing strategies and profit margin calculation

• Promotions and advertising

• Order fulfillment and shipping processes

• Returns handling and abnormal orders

• Operations risks and store suspension prevention

Operations Knowledge MCP Tools

Recommended call order: search first → select chunk_id → read the full evidence → organize the answer.

Agent Call Flow

graph TD
    A[客户提问] --> B{运营知识问题?}
    B -->|是| C[ozon_search_operations_knowledge]
    B -->|API数据问题| F[ozon_search_methods]
    C --> D[选择1-3个chunk_id]
    D --> E[ozon_get_operations_knowledge]
    E --> G{需要当前数据?}
    F --> G
    G -->|是| H[ozon_call_method / ozon_fetch_all]
    G -->|否| I[组织回答]
    H --> I
    I --> J[标注来源与时效风险]

Usage Examples

"Should a beginner start with reselling or curated listing?"

The Agent first calls ozon_search_operations_knowledge({"query": "新手先做跟卖还是精铺"}), then calls ozon_get_operations_knowledge to read the full evidence after getting relevant chunks, and answers based on the lesson content about the pros, cons, and applicable conditions of both models.

"What is a freight forwarder, and what is the complete rFBS shipping process?"

The Agent searches "货代 rFBS 发货流程", retrieves relevant knowledge chunks from lesson 01, and then explains the freight forwarder concept and the complete rFBS chain from order placement to delivery confirmation based on the lesson content.

"How should differentiation be done in curated listing?"

The Agent searches "精铺差异化", retrieves the full evidence on curated listing product selection differentiation strategies from lesson 02, and answers covering product card optimization, main image differentiation, pricing strategy, and other dimensions.

"How should Ozon warehouses and logistics be set up?"

The Agent searches "仓库物流设置" and retrieves detailed warehouse configuration steps and precautions from lesson 06.

"How should product weight be verified before listing?"

The Agent searches "上架前核实重量" and retrieves weight verification methods and common pitfalls from lesson 07.

"What should be checked first when a product has no impressions?"

The Agent searches "商品没有曝光" and retrieves diagnostic approaches from relevant chunks on product cards, pricing, search ranking, and more.

Answer Boundaries

Important note:

• Lesson knowledge is a summary of operations experience and does not equal Ozon's current official rules

• Commissions, fees, logistics times, prohibited items, penalties, advertising, and returns policies may change at any time

• Chunks with verification_required=true must remind customers to re-check current official documentation

• When real store, order, inventory, product, financial, or advertising data is involved, real Ozon APIs must be called

• Content not covered by the knowledge base must not be fabricated

Updating the Knowledge Base

When updating operations knowledge in the future, replace the following files:

• src/ozon_mcp/operations_knowledge/data/manifest.yaml

• src/ozon_mcp/operations_knowledge/data/chunks.jsonl

• src/ozon_mcp/operations_knowledge/data/topics.json

• src/ozon_mcp/operations_knowledge/data/ozon_operations_knowledge.md

Then run validation:

uv run python scripts/validate_operations_knowledge.py
uv run pytest

Use Cases

Scenario 1: Query Pending Fulfillment Orders

"Help me check all orders pending fulfillment"

The Agent first uses ozon_search_methods to search for "order list" or "订单列表", finds OrderAPI_GetOrderList, then uses ozon_describe_method to view the parameter structure, and finally uses ozon_fetch_all to paginate through and pull all orders.

Scenario 2: Stockout Risk Check

"Run the stockout risk analysis workflow and see which SKUs might run out of stock"

The Agent runs ozon_get_workflow({"name": "oos_risk_analysis"}), calls AnalyticsAPI_StocksTurnover following the steps, and flags at-risk SKUs based on the interpretation rules built into the workflow.

Scenario 3: Store Health Check

"Do a comprehensive check of my store status"

The Agent runs ozon_get_workflow({"name": "cabinet_health_check"}), calls the rating, store info, and fulfillment time endpoints in parallel, and summarizes all metrics and statuses.

Scenario 4: Batch Export Product Information

"Pull the basic information of all products currently on sale"

The Agent uses ozon_fetch_all to call ProductAPI_GetProductList, automatically traverses the last_id pagination, and returns the complete product list.

Scenario 5: Not Sure How to Use an API

"Does Ozon have an endpoint for querying warehouse stock? How do I fill in the parameters?"

The Agent uses ozon_search_methods({"query": "warehouse stock"}) to find the corresponding method, then uses ozon_describe_method to get the full parameter schema and call examples, and then helps you construct the request parameters.

System Architecture

graph TD
    A[MCP 客户端<br/>Claude / Cursor / Codex / Windsurf] 
    B[OZON MCP Server<br/>FastMCP stdio]
    C[API 知识层<br/>Swagger + YAML]
    K[运营知识层<br/>BM25 + 中文分词]
    D[Seller API Client<br/>api-seller.ozon.ru]
    E[Performance API Client<br/>api-performance.ozon.ru]
    F[Ozon Seller API]
    G[Ozon Performance API]

    A -->|JSON-RPC over stdio| B
    B --> C
    B --> K
    B --> D
    B --> E
    D -->|Client-Id + Api-Key| F
    E -->|OAuth2 Bearer| G
    
    subgraph 安全守卫
        H[安全等级检查<br/>read/write/destructive]
        I[订阅权限校验]
        J[Schema 验证]
    end
    
    B --> H --> I --> J

Core module description:

• Knowledge layer: Loads complete definitions of 466 methods from built-in Swagger files and the YAML knowledge base at startup

• Search index: BM25-based full-text search engine supporting Chinese/Russian tokenization and field weighting

• Method graph: A method relationship network automatically built from documentation links and workflows

• Rate-limit management: Per-API granularity rate limiting with automatic queuing and backoff retries

• Safety guards: Three-layer validation — security level (read-only/write/destructive) → subscription permission → JSON Schema validation

Project Structure

ozon-mcp/
├── src/ozon_mcp/               # 核心代码
│   ├── __init__.py              # 版本号
│   ├── __main__.py              # CLI 入口，MCP stdio 启动
│   ├── config.py                # 环境变量配置（SecretStr 保护凭据）
│   ├── server.py                # FastMCP 服务器工厂
│   ├── state.py                 # 进程内缓存（订阅等级 TTL）
│   ├── errors.py                # 统一错误模型
│   ├── data/                    # Swagger API 文档
│   │   ├── seller_swagger.json  #   Seller API (420 方法)
│   │   ├── perf_swagger.json    #   Performance API (46 方法)
│   │   └── swagger_meta.json    #   文档版本元数据
│   ├── knowledge/               # 精选知识库（YAML）
│   │   └── ...                   #   工作流、限流、错误码等
│   ├── operations_knowledge/     # 中文运营知识库
│   │   ├── models.py             #   数据模型（Pydantic）
│   │   ├── loader.py             #   加载与完整性校验
│   │   ├── tokenizer.py          #   中文分词器
│   │   ├── search.py             #   BM25 检索引擎
│   │   └── data/                 #   知识库数据
│   │       ├── manifest.yaml     #     元数据
│   │       ├── chunks.jsonl      #     610 个知识片段
│   │       ├── topics.json       #     42 个课程主题
│   │       └── ozon_operations_knowledge.md  # 原始知识文档
│   ├── schema/                  # Schema 引擎
│   │   ├── extractor.py         #   OpenAPI → JSON Schema 提取
│   │   ├── search.py            #   BM25 全文搜索
│   │   ├── graph.py             #   方法关系图 (networkx)
│   │   ├── catalog.py           #   方法目录
│   │   └── resolver.py          #   $ref 内联解析
│   ├── tools/                   # MCP 工具定义（15 个）
│   │   ├── discovery.py         #   发现类工具 (4)
│   │   ├── execution.py         #   执行类工具 (2)
│   │   ├── reference.py         #   参考类工具 (4)
│   │   ├── workflow.py          #   工作流工具 (2)
│   │   ├── subscription.py      #   订阅工具 (2)
│   │   └── graph.py             #   图谱工具 (1)
│   └── transport/               # HTTP 传输层
│       ├── seller.py            #   Seller API 客户端
│       ├── performance.py       #   Performance API 客户端
│       ├── oauth.py             #   OAuth2 Token 管理
│       ├── ratelimit.py         #   速率限制
│       └── base.py              #   基类（重试、错误映射）
├── tests/                       # 测试
│   ├── unit/                    #   单元测试 (25 文件)
│   ├── integration/             #   集成测试 (4 文件)
│   ├── golden/                  #   回归测试 (3 文件)
│   └── live/                    #   真实 API 烟雾测试 (需凭据)
├── scripts/                     # 辅助脚本
│   ├── export_methods.py        #   导出方法目录
│   └── generate_subscription_overrides.py  # 生成订阅覆盖配置
├── Dockerfile                   # 多阶段 Docker 构建
├── pyproject.toml               # 项目配置
├── uv.lock                      # 依赖锁定
└── glama.json                   # Glama MCP 注册

Environment Requirements

Ozon API Permissions

• Seller API: Requires generating Client-Id and Api-Key in the Ozon back office

• Performance API: Requires applying for Client ID and Client Secret

Quick Start

Method 1: Using uv (Recommended)

# 克隆仓库
git clone https://github.com/yifan4243-sketch/OZON_MCP.git
cd OZON_MCP

# 安装依赖
uv sync

# 验证启动
uv run ozon-mcp --help

Seeing the help message means installation succeeded. You can now connect it to an MCP client (see MCP Client Configuration).

Method 2: Using Docker

# 构建镜像
docker build -t ozon-mcp:local .

# 启动（stdio 模式，需要凭据）
docker run -i \
  -e OZON_CLIENT_ID=your_client_id \
  -e OZON_API_KEY=your_api_key \
  ozon-mcp:local

The Docker image does not contain credentials; they must be passed via -e or --env-file.

Environment Variables

All credentials are protected with pydantic.SecretStr and will not be accidentally printed or logged.

See .env.example for configuration examples.

MCP Client Configuration

OZON MCP uses the MCP stdio protocol. The following configurations apply to different MCP clients.

Claude Desktop

Edit the configuration file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ozon": {
      "command": "uv",
      "args": ["--directory", "D:/path/to/ozon-mcp", "run", "ozon-mcp"],
      "env": {
        "OZON_CLIENT_ID": "your_client_id",
        "OZON_API_KEY": "your_api_key"
      }
    }
  }
}

Windows paths use forward slashes or double backslashes, e.g., D:/ozon-mcp or D:\\ozon-mcp.

Claude Code (CLI)

# 在项目目录下执行
claude mcp add ozon -- uv run ozon-mcp

Or manually edit ~/.claude/mcp.json:

{
  "mcpServers": {
    "ozon": {
      "command": "uv",
      "args": ["--directory", "/path/to/ozon-mcp", "run", "ozon-mcp"],
      "env": {
        "OZON_CLIENT_ID": "your_client_id",
        "OZON_API_KEY": "your_api_key"
      }
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "ozon": {
      "command": "uv",
      "args": ["--directory", "/path/to/ozon-mcp", "run", "ozon-mcp"],
      "env": {
        "OZON_CLIENT_ID": "your_client_id",
        "OZON_API_KEY": "your_api_key"
      }
    }
  }
}

Codex

Edit ~/.codex/mcp.json:

{
  "mcpServers": {
    "ozon": {
      "command": "uv",
      "args": ["--directory", "/path/to/ozon-mcp", "run", "ozon-mcp"],
      "env": {
        "OZON_CLIENT_ID": "your_client_id",
        "OZON_API_KEY": "your_api_key"
      }
    }
  }
}

Windsurf

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

{
  "mcpServers": {
    "ozon": {
      "command": "uv",
      "args": ["--directory", "/path/to/ozon-mcp", "run", "ozon-mcp"],
      "env": {
        "OZON_CLIENT_ID": "your_client_id",
        "OZON_API_KEY": "your_api_key"
      }
    }
  }
}

Other MCP Clients

Any client that supports the MCP stdio protocol can connect. Generic configuration:

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

For more clients, see the official MCP client list.

Usage Examples

The following examples show natural-language interactions with OZON MCP through an AI Agent.

Query Type

You: List the modules available in the Ozon Seller API

The Agent calls ozon_list_sections, returning 55 modules and their method counts.

You: Search for all endpoints related to "orders"

The Agent calls ozon_search_methods({"query": "订单"}), returning matching results with scores.

You: View the full documentation for OrderAPI_GetOrderList

The Agent calls ozon_describe_method({"operation_id": "OrderAPI_GetOrderList"}), returning the complete JSON Schema, rate-limit rules, and call examples.

Analysis Type

You: Analyze the overall health of my store

The Agent runs ozon_get_workflow({"name": "cabinet_health_check"}) to get the workflow steps, then calls the rating, store info, and other endpoints step by step, and summarizes the analysis results.

You: Which products are at risk of stockout

The Agent runs ozon_get_workflow({"name": "oos_risk_analysis"}), calls the inventory turnover endpoint, and flags SKUs with DEFICIT and NO_SALES statuses based on the interpretation rules built into the workflow.

Batch Type

You: Pull all products currently on sale for me

The Agent calls ozon_fetch_all({"operation_id": "ProductAPI_GetProductList", "params": {"filter": {"visibility": "ALL"}}}), automatically paginates through, and returns the complete product list.

Troubleshooting Type

You: The product list endpoint returned an error, error code 429

The Agent calls ozon_get_error_catalog({"code": "429"}) to look up the rate-limit error explanation and solution, and also uses ozon_get_rate_limits({"operation_id": "ProductAPI_GetProductList"}) to check the specific rate-limit rules for that endpoint.

Development and Testing

Install Development Dependencies

uv sync --dev

Run Tests

# 运行所有测试（跳过需要真实 API 凭据的测试）
uv run pytest -m "not live"

# 包含覆盖率报告
uv run pytest -m "not live" --cov=src/ozon_mcp --cov-report=term

Code Linting

# Ruff 格式检查
uv run ruff check src/ tests/

# MyPy 类型检查
uv run mypy src/ozon_mcp/

Start Local Service

# 仅知识模式（无需凭据）
uv run ozon-mcp

# 带 Seller API 凭据
OZON_CLIENT_ID=xxx OZON_API_KEY=xxx uv run ozon-mcp

Docker Build

docker build -t ozon-mcp:local .

Security Notes

• Do not commit .env files. All credentials are passed via environment variables; .env is already in .gitignore

• Do not log full credentials. All credential fields are protected with SecretStr; repr() and print() will not leak actual values

• Use least privilege. It is recommended to create a dedicated Ozon API key for the MCP Server with only the required permissions

• Rotate keys regularly. It is recommended to update the API Key in the Ozon back office periodically

• Write operations require human confirmation. All write and destructive operations require an additional confirmation parameter

• Run in a trusted environment. It is recommended to run locally or on a trusted server, and not expose it to the public internet

• Verify platform rules before use. Ozon API rate-limit rules, permission requirements, and fee policies may change

FAQ

MCP Client Cannot Find the Service

Confirm that uv is installed and in PATH:

uv --version

uv Command Not Found

Install uv:

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Environment Variables Not Taking Effect

Confirm the variable names use the OZON_ prefix and are set correctly. You can test with the following command:

OZON_LOG_LEVEL=DEBUG uv run ozon-mcp --help

Ozon API Returns 401 or 403

Check that OZON_CLIENT_ID and OZON_API_KEY are correct and that the keys have not expired.

Request Rate Limit (429)

The server has built-in automatic retry and backoff. If you continue to encounter 429, you can lower the concurrent request rate.

Docker Startup Failure

Confirm Docker is installed and that the build command is run from the project root:

docker build -t ozon-mcp:local .
docker run -i -e OZON_CLIENT_ID=xxx -e OZON_API_KEY=xxx ozon-mcp:local

Windows Path Issues

Use forward slashes or double backslashes for paths in MCP client configuration:

"args": ["--directory", "D:/path/to/ozon-mcp", "run", "ozon-mcp"]

How to Configure Multiple Stores

In the current version, one MCP Server process corresponds to one Ozon account. For multi-store scenarios, you need to start multiple Server instances, each configured with different environment variables.

Operations Knowledge Base Unavailable (knowledge_unavailable)

If the operations knowledge base fails to load at startup (e.g., due to corrupted or missing data files), the three operations knowledge tools still exist, but calling them will return a unified error:

{
  "error": "knowledge_unavailable",
  "error_type": "knowledge_unavailable",
  "message": "中文Ozon运营知识库当前不可用，请检查知识库资源是否完整并重新启动MCP Server。",
  "component": "operations_knowledge",
  "recovery_hint": "检查 src/ozon_mcp/operations_knowledge/data/ 下的 manifest.yaml、chunks.jsonl、topics.json 是否完整，然后重启 MCP Server。"
}

Return field description:

Note: When the knowledge base is unavailable, the API knowledge layer and other tools continue to work normally; only the operations knowledge retrieval functionality is affected. After restoring the knowledge base files, a restart will automatically recover.

License

This project is open-sourced under the MIT License.

Disclaimer

• This project is not an official Ozon project and has no affiliation with Ozon

• Ozon API endpoints, rate limits, commission policies, and permission requirements may change at any time

• Users must comply with the Ozon platform terms of service and applicable laws and regulations

• For write operations and financial operations, manual review is recommended before execution

• This project is not liable for any losses incurred from the use of this software