OZON MCP

Ozon 셀러를 위한 오픈소스 MCP Server, 42개 섹션의 중국어 운영 지식 베이스와 466개의 API 메서드가 내장되어 있어 AI Agent가 운영 경험을 검색하고 Seller/Performance API를 호출하며 실제 비즈니스 작업을 실행할 수 있습니다.

목차

• 프로젝트 소개

• 핵심 기능

• 사용 시나리오

• 시스템 아키텍처

• 프로젝트 구조

• 환경 요구사항

• 빠른 시작

• 환경 변수

• MCP 클라이언트 구성

• 호출 예시

• 개발 및 테스트

• 보안 설명

• 자주 묻는 질문

• 라이선스

• 면책 조항

프로젝트 소개

OZON MCP는 Model Context Protocol 기반의 지식형 MCP Server입니다. Ozon Seller API와 Performance API의 전체 인터페이스 문서, 파라미터 Schema, 속도 제한 규칙 및 비즈니스 워크플로우를 표준화된 MCP 도구로 캡슐화하여 Claude, Cursor, Codex 등 AI Agent가 Ozon API를 직접 검색하고 이해하며 호출할 수 있게 합니다.

어떤 문제를 해결하나

Ozon 오픈 플랫폼에는 두 세트의 API(Seller + Performance)가 있으며 총 460개 이상의 인터페이스가 55개 비즈니스 모듈에 분산되어 있습니다. 문서를 수동으로 조회하고, 요청을 조합하며, 페이지네이션과 속도 제한을 처리하는 것은 매우 시간이 많이 걸립니다.

OZON MCP는 AI Agent를 여러분의 Ozon 운영 도우미로 만듭니다:

• Agent는 중국어 또는 러시아어로 API 메서드를 검색하여 필요한 인터페이스를 찾을 수 있습니다

• 각 메서드는 완전히 파싱된 JSON Schema를 반환하며, 요청 파라미터, 응답 구조, 속도 제한 규칙 및 알려진 함정을 포함합니다

• 쓰기 작업 실행 시 다층 안전 가드가 있어 오작동을 방지합니다

• 자동 페이지네이션으로 대량 데이터를 순회할 수 있습니다

• 13개의 선별된 비즈니스 워크플로우가 내장되어 있어 품절 분석, 가격 진단, 쇼핑몰 건강 검진 등의 시나리오를 다룹니다

누가 사용하면 좋을까

• AI로 일상 운영 분석을 보조하고 싶은 Ozon 셀러

• Agent에 Ozon 기능을 통합해야 하는 크로스보더 전자상거래 도구 개발자

• MCP 프로토콜에 관심이 있고 실제 적용 사례를 알고 싶은 개발자

핵심 기능

API 발견 및 탐색

비즈니스 워크플로우

13개의 선별된 워크플로우로 다음 비즈니스 카테고리를 다룹니다:

각 워크플로우에는: 작업 단계 시퀀스, 페이지네이션/동시성 지침, 권장 데이터베이스 Schema, 알려진 함정 및 결과 해석 설명이 포함됩니다.

안전한 실행

참고 정보

구독 권한

참고: 현재 버전은 지식 서버입니다 — API 자격 증명을 구성하지 않아도 모든 발견, 검색, 참고 및 워크플로우 도구를 정상적으로 사용할 수 있습니다. 실제 API 호출을 실행해야 할 때만 자격 증명 구성이 필요합니다.

API 메서드 전체 보기

프로젝트에는 466개의 Ozon API 메서드에 대한 완전한 중국어 카탈로그(methods_catalog.md)가 내장되어 있으며, Ozon 셀러 비즈니스의 모든 영역을 다룹니다:

Agent는 접속 후 중국어로 검색할 수 있으며(예: "주문 목록 조회", "재고 일괄 업데이트"), 카탈로그 카드 형식의 중국어 설명과 결합하여 올바른 API를 빠르게 찾아 호출을 실행할 수 있습니다. 각 메서드에는 HTTP 메서드, 인터페이스 경로, 보안 등급 및 구독 요구사항이 표시되어 있어, Agent는 이를 기반으로 쓰기 작업 확인이나 상위 구독 권한이 필요한지 직접 판단할 수 있습니다.

중국어 Ozon 운영 지식 베이스

프로젝트에는 완전한 중국어 Ozon 운영 지식 베이스가 내장되어 있으며, 42개 섹션의 Ozon 전자상거래 강좌를 기반으로 정리된 610개의 검색 가능한 지식 조각이 포함됩니다. Agent는 중국어 자연어로 검색하여 운영 경험, 작업 절차 및 함정 회피 가이드를 빠르게 찾을 수 있습니다.

지식 베이스 개요

다루는 주제

지식 베이스는 Ozon 셀러의 개점부터 사후 관리까지의 전체 프로세스를 다룹니다:

• 플랫폼 운영 모델(따라팔기, 정교한 운영, 대량 상품 등록, 드롭쉬핑)

• FBS, FBO, FBP, rFBS 네 가지 이행 모드

• 쇼핑몰 등록 및 국제 운임 계산

• 창고 설정 및 물류 구성

• 상품 선정 방법 및 선정 풀 구축

• 상품 중량 및 크기 검증

• 셀러 백오피스 모듈 상세 설명

• 상품 카드 최적화 및 메인 이미지 제작

• 가격 전략 및 이익률 계산

• 프로모션 활동 및 광고 홍보

• 주문 발생 및 배송 프로세스

• 반품 처리 및 이상 주문

• 운영 리스크 및 쇼핑몰 폐쇄 방지

운영 지식 MCP 도구

권장 호출 순서: 먼저 검색 → chunk_id 선택 → 전체 증거 읽기 → 답변 구성.

Agent 호출 흐름

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

호출 예시

"초보자는 먼저 따라팔기와 정교한 운영 중 무엇을 해야 하나요?"

Agent는 먼저 ozon_search_operations_knowledge({"query": "초보자 따라팔기 정교한 운영"})를 호출하여 관련 조각을 얻은 후 ozon_get_operations_knowledge를 호출하여 전체 증거를 읽고, 강좌 내용을 기반으로 두 모드의 장단점과 적용 조건을 답변합니다.

"물류 대행이 무엇인가요, rFBS 전체 배송 프로세스는 무엇인가요?"

Agent는 "물류 대행 rFBS 배송 프로세스"를 검색하여 lesson 01 관련 지식 조각을 얻은 후, 강좌 내용과 결합하여 물류 대행 개념과 rFBS의 주문 발생부터 수령까지의 전체 프로세스를 설명합니다.

"정교한 운영에서 차별화는 어떻게 해야 하나요?"

Agent는 "정교한 운영 차별화"를 검색하여 lesson 02에서 정교한 운영 상품 선정 차별화 전략의 전체 증거를 얻고, 상품 카드 최적화, 메인 이미지 차별화, 가격 전략 등의 차원을 포함하여 답변합니다.

"Ozon 창고와 물류는 어떻게 설정해야 하나요?"

Agent는 "창고 물류 설정"을 검색하여 lesson 06에서 창고 구성의 상세 단계와 주의사항을 얻습니다.

"상품 등록 전에 중량은 어떻게 확인해야 하나요?"

Agent는 "등록 전 중량 확인"을 검색하여 lesson 07에서 중량 검증의 작업 방법과 일반적인 함정을 얻습니다.

"상품 노출이 없으면 먼저 무엇을 확인해야 하나요?"

Agent는 "상품 노출 없음"을 검색하여 상품 카드, 가격, 검색 순위 등 관련 조각의 진단 방향을 얻습니다.

답변 경계

중요 안내:

• 강좌 지식은 운영 경험 요약으로, 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: 배송 대기 주문 조회

"배송 대기 중인 모든 주문을 조회해줘"

Agent는 먼저 ozon_search_methods로 "order list" 또는 "주문 목록"을 검색하여 OrderAPI_GetOrderList를 찾은 후, ozon_describe_method로 파라미터 구조를 확인하고, 마지막으로 ozon_fetch_all로 페이지네이션하여 전체 주문을 가져옵니다.

시나리오 2: 품절 위험 확인

"품절 위험 분석 워크플로우를 실행해서 어떤 SKU가 품절될 수 있는지 확인해줘"

Agent는 ozon_get_workflow({"name": "oos_risk_analysis"})를 실행하고, 단계에 따라 AnalyticsAPI_StocksTurnover를 호출하며, 워크플로우에 내장된 해석 규칙에 따라 위험 SKU를 표시합니다.

시나리오 3: 쇼핑몰 건강 검진

"내 쇼핑몰 상태를 종합적으로 점검해줘"

Agent는 ozon_get_workflow({"name": "cabinet_health_check"})를 실행하고, 평점, 쇼핑몰 정보, 배송 기간 세 가지 인터페이스를 병렬로 호출하여 각 지표와 상태를 종합합니다.

시나리오 4: 상품 정보 일괄 내보내기

"판매 중인 모든 상품의 기본 정보를 가져와줘"

Agent는 ozon_fetch_all로 ProductAPI_GetProductList를 호출하고, last_id 페이지네이션을 자동으로 순회하여 전체 상품 목록을 반환합니다.

시나리오 5: 특정 API 사용법을 모를 때

"Ozon에 창고 재고를 조회하는 인터페이스가 있나요? 파라미터는 어떻게 입력하나요?"

Agent는 ozon_search_methods({"query": "warehouse stock"})로 해당 메서드를 찾은 후, ozon_describe_method로 전체 파라미터 Schema와 호출 예시를 얻고, 요청 파라미터 조합을 도와줍니다.

시스템 아키텍처

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 기반 전문 검색 엔진, 중러문 토큰화 및 필드 가중치 지원

• 메서드 그래프: 문서 링크와 워크플로우를 기반으로 자동 구축된 메서드 관계 네트워크

• 속도 제한 관리: per-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 Agent를 통해 OZON MCP를 사용하는 자연어 상호작용 방식을 보여줍니다.

조회 유형

사용자: Ozon Seller API에 어떤 모듈이 있는지 나열해줘

Agent가 ozon_list_sections를 호출하여 55개 모듈과 메서드 수를 반환합니다.

사용자: "주문"과 관련된 모든 인터페이스를 검색해줘

Agent가 ozon_search_methods({"query": "주문"})를 호출하여 일치 결과와 점수를 반환합니다.

사용자: OrderAPI_GetOrderList의 전체 문서를 확인해줘

Agent가 ozon_describe_method({"operation_id": "OrderAPI_GetOrderList"})를 호출하여 전체 JSON Schema, 속도 제한 규칙 및 호출 예시를 반환합니다.

분석 유형

사용자: 내 쇼핑몰의 전반적인 건강 상태를 분석해줘

Agent가 ozon_get_workflow({"name": "cabinet_health_check"})를 실행하여 워크플로우 단계를 얻은 후, 단계에 따라 평점, 쇼핑몰 정보 등의 인터페이스를 호출하여 분석 결과를 종합합니다.

사용자: 어떤 상품에 품절 위험이 있나요

Agent가 ozon_get_workflow({"name": "oos_risk_analysis"})를 실행하고, 재고 회전율 인터페이스를 호출하며, 워크플로우에 내장된 해석 규칙에 따라 DEFICIT 및 NO_SALES 상태의 SKU를 표시합니다.

일괄 유형

사용자: 판매 중인 모든 상품을 가져와줘

Agent가 ozon_fetch_all({"operation_id": "ProductAPI_GetProductList", "params": {"filter": {"visibility": "ALL"}}})를 호출하여 자동 페이지네이션 순회 후 전체 상품 목록을 반환합니다.

이상 원인 조사 유형

사용자: 상품 목록 인터페이스 호출 시 오류가 발생했는데 오류 코드가 429야

Agent가 ozon_get_error_catalog({"code": "429"})를 호출하여 속도 제한 오류의 설명과 해결 방법을 조회하고, 동시에 ozon_get_rate_limits({"operation_id": "ProductAPI_GetProductList"})로 해당 인터페이스의 구체적인 속도 제한 규칙을 확인합니다.

개발 및 테스트

개발 의존성 설치

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 Server 전용 Ozon API 키를 별도로 생성하고 필요한 권한만 부여하는 것을 권장합니다

• 키를 정기적으로 교체. Ozon 백오피스에서 API Key를 정기적으로 업데이트하는 것을 권장합니다

• 쓰기 작업은 수동 확인 필요. 모든 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"]

다중 쇼핑몰 구성 방법

현재 버전은 하나의 MCP Server 프로세스가 하나의 Ozon 계정에 해당합니다. 다중 쇼핑몰 시나리오에서는 여러 Server 인스턴스를 시작하고 각각 다른 환경 변수를 구성해야 합니다.

운영 지식 베이스를 사용할 수 없음(knowledge_unavailable)

시작 시 운영 지식 베이스 로드에 실패하면(예: 데이터 파일 손상 또는 누락), 세 가지 운영 지식 도구는 여전히 존재하지만 호출 시 통일된 오류가 반환됩니다:

{
  "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 플랫폼 서비스 약관 및 적용 가능한 법률을 준수해야 합니다.

• 쓰기 작업 및 자금 작업과 관련된 경우 수동 검토 후 실행하는 것이 좋습니다.

• 이 프로젝트는 본 소프트웨어 사용으로 인해 발생하는 어떠한 손실에 대해서도 책임을 지지 않습니다.