OZON MCP

Ozon セラー向けのオープンソース MCP サーバー。42 セクションの中国語運営ナレッジベースと 466 の API メソッドを内蔵し、AI エージェントが運用ノウハウの検索、Seller/Performance API の呼び出し、実際のビジネス操作の実行を可能にします。

目次

• プロジェクト概要

• コア機能

• ユースケース

• システムアーキテクチャ

• プロジェクト構成

• 必要環境

• クイックスタート

• 環境変数

• MCP クライアント設定

• 呼び出し例

• 開発とテスト

• セキュリティについて

• よくある質問

• ライセンス

• 免責事項

プロジェクト概要

OZON MCP は、Model Context Protocol に基づくナレッジ型 MCP サーバーです。Ozon Seller API と Performance API の完全なインターフェースドキュメント、パラメータスキーマ、レート制限ルール、ビジネスワークフローを標準化された MCP ツールとしてカプセル化し、Claude、Cursor、Codex などの AI エージェントが Ozon API を直接検索・理解・呼び出しできるようにします。

何を解決するのか

Ozon オープンプラットフォームには 2 セットの API（Seller + Performance）があり、55 のビジネスモジュールに分散する 460 以上のエンドポイントがあります。ドキュメントの手動参照、リクエストの組み立て、ページネーションやレート制限への対応には非常に時間がかかります。

OZON MCP は AI エージェントをあなたの Ozon 運用アシスタントに変えます：

• エージェントは中国語またはロシア語で API メソッドを検索し、必要なエンドポイントを見つけられます

• 各メソッドは完全にパースされた JSON Schema（リクエストパラメータ、レスポンス構造、レート制限ルール、既知の落とし穴を含む）を返します

• 書き込み操作には複数層のセーフティガードがあり、誤操作を防止します

• 大量データの一括取得には自動ページネーションをサポート

• 13 の厳選ビジネスワークフローを内蔵し、在切れ分析、価格診断、ストアヘルスチェックなどのシナリオをカバー

こんな方におすすめ

• 日常の運用分析に AI を活用したい Ozon セラー

• エージェントに Ozon 機能を統合したい越境 EC ツール開発者

• MCP プロトコルに興味があり、実際の導入事例を知りたい開発者

コア機能

API 検出とナビゲーション

ビジネスワークフロー

13 の厳選ワークフローで、以下のビジネスカテゴリをカバー：

各ワークフローには、操作手順シーケンス、ページネーション/並行処理のガイダンス、推奨データベーススキーマ、既知の落とし穴、結果の解釈手順が含まれています。

安全な実行

リファレンス情報

サブスクリプション権限

注意：現在のバージョンはナレッジサーバーです。API 資格情報を設定しなくても、すべての検出・検索・リファレンス・ワークフローツールが正常に動作します。実際の API 呼び出しを実行する場合にのみ、資格情報の設定が必要です。

API メソッド全体像

プロジェクトには 466 の Ozon API メソッドの完全な中国語カタログ（methods_catalog.md）が組み込まれており、Ozon セラービジネスの全領域をカバーしています：

エージェントは中国語で検索（例：「注文リストを照会」、「在庫を一括更新」）でき、カタログカード形式の中国語説明と組み合わせて、正しい API をすばやく見つけて呼び出すことができます。各メソッドには HTTP メソッド、API パス、セキュリティレベル、サブスクリプション要件が記載されているため、エージェントは書き込み操作の確認や上位サブスクリプション権限が必要かどうかを直接判断できます。

中国語 Ozon 運用ナレッジベース

プロジェクトには、42 レッスンの Ozon 越境 EC コースに基づく完全な中国語 Ozon 運用ナレッジベースが組み込まれており、610 の検索可能なナレッジチャンクが含まれています。エージェントは中国語の自然言語で検索し、運用ノウハウ、操作手順、注意点をすばやく見つけることができます。

ナレッジベース概要

対象トピック

ナレッジベースは、Ozon セラーの出店からアフターサービスまでの全プロセスをカバーしています：

• プラットフォームのビジネスモデル（横流し出品、厳選出品、大量出品、ドロップシッピング）

• FBS、FBO、FBP、rFBS の 4 つのフルフィルメントモデル

• ストア登録と国際送料の計算

• 倉庫設定と物流構成

• 商品リサーチ方法とリサーチプールの構築

• 商品の重量・サイズ検証

• セラー管理画面モジュールの詳細

• 商品カードの最適化とメイン画像の作成

• 価格戦略と利益率の計算

• プロモーションキャンペーンと広告宣伝

• 注文処理と出荷フロー

• 返品処理と異常注文

• 運用リスクとアカウント停止の防止

運用ナレッジ MCP ツール

推奨される呼び出し順序：まず検索 → chunk_id を選択 → 完全なエビデンスを読み込む → 回答を構成。

エージェント呼び出しフロー

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[标注来源与时效风险]

呼び出し例

「初心者はまず横流し出品と厳選出品のどちらをやるべき？」

エージェントはまず ozon_search_operations_knowledge({"query": "初心者 横流し 厳選"}) を呼び出し、関連チャンクを取得した後、ozon_get_operations_knowledge を呼び出して完全なエビデンスを読み込み、コース内容に基づいて両モデルの長所・短所と適用条件を回答します。

「フォワーダーとは何か、rFBS の完全な出荷フローは？」

エージェントは "フォワーダー rFBS 出荷フロー" を検索し、レッスン 01 の関連ナレッジチャンクを取得した後、コース内容と組み合わせてフォワーダーの概念と、注文から配達完了までの rFBS の完全な流れを説明します。

「厳選出品で差別化するにはどうすればいい？」

エージェントは "厳選 差別化" を検索し、レッスン 02 から厳選出品の差別化戦略の完全なエビデンスを取得し、商品カード最適化、メイン画像の差別化、価格戦略などの観点から回答します。

「Ozon の倉庫と物流はどう設定すればいい？」

エージェントは "倉庫 物流 設定" を検索し、レッスン 06 から倉庫設定の詳細な手順と注意点を取得します。

「商品を出品する前に重量をどう確認すればいい？」

エージェントは "出品前 重量確認" を検索し、レッスン 07 から重量検証の操作方法とよくある落とし穴を取得します。

「商品の露出がない場合、最初に何を確認すべき？」

エージェントは "商品 露出なし" を検索し、商品カード、価格、検索ランキングなどの関連チャンクから診断の考え方を取得します。

回答の境界

重要な注意：

• コースの知識は運用ノウハウのまとめであり、Ozon の現在の公式ルールと同一ではありません

• 手数料、レート、物流リードタイム、販売禁止商品、ペナルティ、広告、返品ポリシーは随時変更される可能性があります

• verification_required=true のチャンクは、お客様に現在の公式情報の再確認を促す必要があります

• お客様の実際のストア、注文、在庫、商品、財務、広告データに関わる場合は、必ず実際の Ozon API を呼び出す必要があります

• ナレッジベースでカバーされていない内容は、推測で回答してはいけません

ナレッジベースの更新

今後、運用ナレッジを更新する際は、以下のファイルを置き換えます：

• 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

その後、検証を実行します：

uv run python scripts/validate_operations_knowledge.py
uv run pytest

ユースケース

シナリオ 1：未出荷注文の照会

「未出荷の注文をすべて確認して」

エージェントはまず ozon_search_methods で「order list」または「注文リスト」を検索して OrderAPI_GetOrderList を見つけ、ozon_describe_method でパラメータ構造を確認し、最後に ozon_fetch_all で全注文をページネーションで取得します。

シナリオ 2：在切れリスクチェック

「在切れリスク分析ワークフローを実行して、在庫切れになりそうな SKU を確認して」

エージェントは ozon_get_workflow({"name": "oos_risk_analysis"}) を実行し、手順に従って AnalyticsAPI_StocksTurnover を呼び出し、ワークフローに組み込まれた解釈ルールに基づいてリスク SKU をフラグ付けします。

シナリオ 3：ストアのヘルスチェック

「私のストアの状態を総合的にチェックして」

エージェントは ozon_get_workflow({"name": "cabinet_health_check"}) を実行し、評価、ストア情報、配送リードタイムの 3 つの API を並行して呼び出し、各指標とステータスを集約します。

シナリオ 4：商品情報の一括エクスポート

「販売中商品の基本情報をすべて取得して」

エージェントは ozon_fetch_all を使用して ProductAPI_GetProductList を呼び出し、last_id ページネーションを自動的に走査して、完全な商品リストを返します。

シナリオ 5：API の使い方がわからない場合

「Ozon に倉庫在庫を照会する API はある？パラメータはどう入力するの？」

エージェントは ozon_search_methods({"query": "warehouse stock"}) で該当メソッドを見つけ、ozon_describe_method で完全なパラメータスキーマと呼び出し例を取得し、リクエストパラメータの組み立てを支援します。

システムアーキテクチャ

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

コアモジュールの説明：

• ナレッジレイヤー：起動時に内蔵の Swagger ファイルと YAML ナレッジベースから 466 メソッドの完全な定義をロード

• 検索インデックス：BM25 ベースの全文検索エンジン。中国語・ロシア語の分かち書きとフィールド重み付けに対応

• メソッドグラフ：ドキュメントリンクとワークフローに基づいて自動構築されるメソッドの関係ネットワーク

• レート制限管理：API 単位のレート制限。自動キューイングとバックオフリトライ

• セキュリティガード：3 層の検証——セキュリティレベル（読み取り専用/書き込み/破壊的）→ サブスクリプション権限 → JSON Schema 検証

プロジェクト構成

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 注册

必要環境

Ozon API 権限

• Seller API：Ozon 管理画面で Client-Id と Api-Key を生成する必要があります

• Performance API：Client ID と Client Secret の申請が必要です

クイックスタート

方法 1：uv を使用（推奨）

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

# 安装依赖
uv sync

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

ヘルプ情報が表示されればインストール成功です。この時点で MCP クライアントに接続できます（MCP クライアント設定 を参照）。

方法 2：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

Docker イメージには資格情報が含まれていません。-e または --env-file で渡す必要があります。

環境変数

すべての資格情報は pydantic.SecretStr で保護されており、誤って印刷されたりログに記録されたりすることはありません。

設定例は .env.example を参照してください。

MCP クライアント設定

OZON MCP は MCP stdio プロトコルを使用します。以下の設定はさまざまな MCP クライアントに適用されます。

Claude Desktop

設定ファイルを編集します：

• 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 のパスはスラッシュまたは二重バックスラッシュを使用します。例：D:/ozon-mcp または D:\\ozon-mcp。

Claude Code (CLI)

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

または ~/.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、または ~/.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

~/.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

~/.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"
      }
    }
  }
}

その他の MCP クライアント

MCP stdio プロトコルをサポートするクライアントはすべて接続できます。汎用設定：

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

その他のクライアントについては MCP 公式クライアントリスト を参照してください。

呼び出し例

以下の例は、AI エージェントを介した OZON MCP の自然言語インタラクションの使用方法を示しています。

照会系

あなた：Ozon Seller API のモジュールを一覧表示して

エージェントは ozon_list_sections を呼び出し、55 のモジュールとそのメソッド数を返します。

あなた：「注文」に関連するすべての API を検索して

エージェントは ozon_search_methods({"query": "注文"}) を呼び出し、一致した結果とスコアを返します。

あなた：OrderAPI_GetOrderList の完全なドキュメントを表示して

エージェントは ozon_describe_method({"operation_id": "OrderAPI_GetOrderList"}) を呼び出し、完全な JSON Schema、レート制限ルール、呼び出し例を返します。

分析系

あなた：私のストアの全体的な健全性を分析して

エージェントは ozon_get_workflow({"name": "cabinet_health_check"}) を実行してワークフローの手順を取得し、手順に従って評価、ストア情報などの API を呼び出し、分析結果を集約します。

あなた：在切れリスクのある商品はどれ？

エージェントは ozon_get_workflow({"name": "oos_risk_analysis"}) を実行し、在庫回転 API を呼び出し、ワークフローに組み込まれた解釈ルールに基づいて DEFICIT および NO_SALES ステータスの SKU をフラグ付けします。

一括処理系

あなた：販売中商品をすべて取得して

エージェントは ozon_fetch_all({"operation_id": "ProductAPI_GetProductList", "params": {"filter": {"visibility": "ALL"}}}) を呼び出し、自動ページネーションで完全な商品リストを返します。

例外調査系

あなた：商品リスト API の呼び出しでエラーになった。エラーコード 429

エージェントは ozon_get_error_catalog({"code": "429"}) を呼び出してレート制限エラーの説明と解決策を確認し、同時に ozon_get_rate_limits({"operation_id": "ProductAPI_GetProductList"}) でその API の具体的なレート制限ルールを確認します。

開発とテスト

開発用依存関係のインストール

uv sync --dev

テストの実行

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

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

コードチェック

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

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

ローカルサーバーの起動

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

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

Docker ビルド

docker build -t ozon-mcp:local .

セキュリティについて

• .env ファイルをコミットしないでください。すべての資格情報は環境変数を介して渡され、.env は .gitignore に追加されています

• ログに完全な資格情報を記録しないでください。すべての資格情報フィールドは SecretStr で保護されており、repr() や print() で実際の値が漏洩することはありません

• 最小権限を使用してください。MCP サーバー専用の Ozon API キーを作成し、必要な権限のみを付与することをお勧めします

• キーを定期的にローテーションしてください。Ozon 管理画面で API キーを定期的に更新することをお勧めします

• 書き込み操作は人間の確認が必要です。すべての write および destructive 操作には追加の確認パラメータが必要です

• 信頼できる環境で実行してください。ローカルまたは信頼できるサーバーでの実行を推奨し、パブリックネットワークに公開しないでください

• プラットフォームのルールを確認してください。Ozon API のレート制限ルール、権限要件、料金ポリシーは変更される可能性があります

よくある質問

MCP クライアントがサービスを見つけられない

uv がインストールされ、PATH に含まれていることを確認してください：

uv --version

uv コマンドが見つからない

uv をインストール：

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

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

環境変数が反映されない

変数名が OZON_ プレフィックスで始まり、正しく設定されていることを確認してください。以下のコマンドでテストできます：

OZON_LOG_LEVEL=DEBUG uv run ozon-mcp --help

Ozon API が 401 または 403 を返す

OZON_CLIENT_ID と OZON_API_KEY が正しいか、キーが期限切れでないかを確認してください。

リクエスト頻度制限（429）

サーバーには自動リトライとバックオフメカニズムが組み込まれています。429 が続く場合は、同時リクエスト頻度を下げてください。

Docker の起動に失敗する

Docker がインストールされていること、ビルドコマンドがプロジェクトルートで実行されていることを確認してください：

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

Windows のパス問題

MCP クライアント設定のパスはスラッシュまたは二重バックスラッシュを使用します：

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

複数ストアの設定方法

現在のバージョンでは、1 つの MCP サーバープロセスが 1 つの Ozon アカウントに対応します。複数ストアのシナリオでは、複数のサーバーインスタンスを起動し、それぞれに異なる環境変数を設定する必要があります。

運用ナレッジベースが利用不可（knowledge_unavailable）

起動時に運用ナレッジベースの読み込みに失敗した場合（データファイルの破損や欠落など）、3つの運用ナレッジツールは引き続き存在しますが、呼び出し時に統一されたエラーが返されます：

{
  "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。"
}

返却フィールドの説明：

注意：ナレッジベースが利用できない場合、API ナレッジレイヤーや他のツールは正常に動作し続け、運用ナレッジの検索機能のみが影響を受けます。ナレッジベースファイルを復元して再起動すると、自動的に復旧します。

ライセンス

本プロジェクトは MIT License に基づきオープンソースです。

免責事項

• 本プロジェクトは Ozon 公式のプロジェクトではなく、Ozon 公式との所属関係はありません

• Ozon API のインターフェース、レート制限ルール、手数料ポリシー、権限要件は随時変更される可能性があります

• 利用者は Ozon プラットフォームの利用規約および適用される法令を自ら遵守する必要があります

• 書き込み操作や資金操作に関わる場合は、人による再確認を行ってから実行することを推奨します

• 本プロジェクトは、本ソフトウェアの使用により生じたいかなる損失についても責任を負いません