Skip to main content
Glama
deenesjakoruzh
PCDCK

ozon-mcp

by PCDCK
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

ozon-mcp

Ozon Seller 및 Performance API를 위한 MCP 서버입니다. 몇 분 안에 모든 AI 에이전트를 Ozon 계정과 연결하세요.

CI Python License MCP

ozon-mcp는 Ozon 판매자 툴킷 전체를 15개의 고효율 도구로 변환하는 지식 집약적 MCP 서버입니다. AI 에이전트(Claude, Cursor, Cline, Continue, Goose, Zed 등)는 러시아어 또는 영어로 API를 검색하고, 완전히 해석된 JSON 스키마를 통해 466개의 메서드 중 무엇이든 자세히 살펴볼 수 있으며, 내장된 안전 장치를 통해 호출을 실행할 수 있습니다. 구독 인식, 4가지 커서 스타일에 대한 자동 페이지네이션, 429 오류 시 재시도/백오프 기능, 그리고 바로 사용할 수 있는 13가지 분석 워크플로우를 지원합니다.

주요 사실: 466개의 인덱싱된 메서드(Seller 420개 + Performance 46개), 55개의 섹션, 5개의 구독 등급 모델링, 38개의 페이지네이션 엔드포인트 자동 탐색, 43개의 파괴적 메서드 이중 잠금 장치, 일반적인 판매자 시나리오를 위한 13개의 큐레이팅된 워크플로우.

빠른 시작

사전 요구 사항

  • Python 3.12 또는 3.13

  • uv 패키지 관리자 — 다음 명령어로 설치: curl -LsSf https://astral.sh/uv/install.sh | sh

  • Ozon Seller API 자격 증명(Client-Id + Api-Key) — 다음에서 확인: https://seller.ozon.ru/app/settings/api-keys

설치

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

작동 확인

uv run ozon-mcp --help

FastMCP 사용 라인이 표시되어야 합니다. 서버는 MCP stdio 프로토콜을 사용하므로 호환되는 모든 클라이언트를 연결할 수 있습니다(아래 지침 참조).

Related MCP server: Avito MCP

AI 에이전트 연결

ozon-mcp는 표준 MCP stdio 전송을 사용합니다. 아래의 모든 예제는 동일한 15개의 도구를 제공하므로, 이미 사용 중인 클라이언트를 선택하세요.

Claude Desktop

다음 파일을 편집하세요: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 %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

또는 위 Claude Desktop 설정과 동일한 형식으로 ~/.claude/mcp.json에 추가하세요.

Cursor

설정(Settings) → MCP → 새 MCP 서버 추가, 또는 ~/.cursor/mcp.json 편집:

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

Windsurf

~/.codeium/windsurf/mcp_config.json 편집:

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

Cline (VS Code 확장 프로그램)

Cline → 설정(Settings) → MCP 서버(MCP Servers) → 추가:

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

Continue.dev

~/.continue/config.json 편집:

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

Goose, Zed 또는 기타 MCP 클라이언트

MCP stdio를 지원하는 모든 클라이언트에서 작동합니다. 일반 설정:

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

공식 MCP 클라이언트 목록은 https://modelcontextprotocol.io/clients에서 확인하세요.

사용 예시

아래의 모든 예시는 tests/fixtures/responses/에서 복사한 실제 응답을 보여줍니다. 식별자(99000001, TEST-SKU-001)는 익명화되었지만 실제 형태를 유지합니다.

예시 1 — 모든 상품 가져오기

사용자: operation_id="ProductAPI_GetProductList"와 함께 ozon_fetch_all을 사용하여 내 모든 상품을 가져와줘.

에이전트 호출:

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

서버가 last_id 커서를 자동으로 탐색하고 다음을 반환합니다:

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

예시 2 — 재고 부족 위험이 있는 상품 찾기

사용자: 내 계정에 대해 oos_risk_analysis 워크플로우를 실행해줘.

에이전트가 먼저 워크플로우를 검사합니다:

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

→ 에이전트에게 AnalyticsAPI_StocksTurnover를 호출하도록 지시합니다(1분당 1회 요청으로 제한됨 — 서버의 엔드포인트별 큐가 이를 처리합니다). 또한 turnover_grade를 해석하는 방법을 알려줍니다. 호출 결과:

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

워크플로우의 interpret 필드는 에이전트에게 idc < 14 또는 turnover_grade ∈ {DEFICIT, NO_SALES}인 SKU를 표시하고 idc asc 순으로 정렬하도록 지시합니다.

예시 3 — 전체 계정 상태 점검

사용자: cabinet_health_check 워크플로우를 사용하여 내 Ozon 계정 상태를 확인해줘.

워크플로우는 에이전트에게 RatingAPI_RatingSummaryV1, SellerAPI_SellerInfo, AverageDeliveryTimeSummary 세 가지 엔드포인트를 병렬로 읽도록 지시합니다. 첫 번째 호출 결과:

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

예시 4 — 상품 가격 분석

사용자: 내 상품 중 가격 지수가 빨간색인 것은 무엇인가요?

에이전트가 pricing_analysis 워크플로우를 실행하고 모든 항목의 price_indexes.color_index 필드를 검사합니다:

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

워크플로우의 common_mistakes 목록은 에이전트에게 기본 price뿐만 아니라 marketing_seller_price(실제 구매자에게 표시되는 가격)와 비교하도록 상기시킵니다.

예시 5 — 콘텐츠 감사

사용자: 콘텐츠 등급이 낮은 상품을 찾아서 개선 방법을 알려줘.

에이전트가 content_audit을 실행하여 SKU별 등급과 점수를 높일 수 있는 속성 목록을 가져옵니다:

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

워크플로우는 에이전트에게 rating을 +10 올리면 검색 순위가 눈에 띄게 향상된다고 알려주므로, 해당 두 가지 속성을 채우는 것이 약 4점의 가치가 있음을 알 수 있습니다.

사용 가능한 도구 (15)

도구

기능

ozon_call_method

안전 및 구독 제한을 적용하여 Ozon API 메서드 실행

ozon_fetch_all

자동 페이지네이션 — 첫 페이지뿐만 아니라 모든 페이지 가져오기

ozon_describe_method

메서드에 대한 전체 문서: 스키마, 예제, 속도 제한, 특이 사항

ozon_search_methods

466개 메서드에 대한 BM25 검색(러시아어 또는 영어, 어간 추출 지원)

ozon_list_sections

섹션별로 API 탐색

ozon_get_section

한 섹션 내의 모든 메서드

ozon_list_workflows

준비된 분석 워크플로우 목록(카테고리별 필터링 가능)

ozon_get_workflow

워크플로우에 대한 전체 단계별 계획

ozon_get_related_methods

함께 사용하기 좋은 메서드(자동 추출된 그래프)

ozon_get_examples

메서드에 대한 큐레이팅된 요청/응답 예제

ozon_get_rate_limits

메서드별, 섹션별 또는 전체 속도 제한 확인

ozon_get_subscription_status

현재 계정의 구독 등급 확인

ozon_list_methods_for_subscription

특정 등급에서 잠금 해제되는 기능 확인

ozon_get_swagger_meta

번들된 API 사양이 최신인지 확인

ozon_get_error_catalog

Ozon 오류 코드 조회

준비된 워크플로우 (13)

워크플로우는 큐레이팅된 단계별 레시피입니다. ozon_get_workflow("name")을 사용하여 interpret, when_to_use, common_mistakes 및 동기화 스타일 워크플로우를 위한 권장 DB 스키마를 포함한 전체 계획을 가져오세요.

워크플로우

카테고리

해결 과제

oos_risk_analysis

분석

재고 부족 위험이 있는 상품 찾기

cabinet_health_check

상태

모든 판매자 등급 지표를 한 번에 확인

content_audit

콘텐츠

콘텐츠 등급이 낮은 카드 찾기 + 실행 가능한 속성

pricing_analysis

가격

경쟁력이 없는 가격의 상품 찾기

warehouse_stock_distribution

창고

FBO를 위한 창고별 재고 분석

sync_products_catalog

카탈로그

전체 상품 카탈로그 스냅샷

sync_orders_fbo

주문

증분 FBO 주문 동기화

sync_orders_fbs

주문

증분 FBS / rFBS 주문 동기화

sync_finance_transactions

재무

단위 경제 분석을 위한 재무 거래

sync_analytics_daily

분석

일일 매출 / 주문 시계열

sync_advertising_campaigns

광고

Performance API 광고 카탈로그

sync_warehouse_stocks

창고

FBS 창고 재고

sync_returns_rfbs

반품

rFBS 반품 동기화

API 커버리지

API

메서드

섹션

Ozon Seller API

420

49

Ozon Performance API

46

6

합계

466

55

모델링된 구독 등급(낮음 → 높음): LITE → STANDARD → PREMIUM → PREMIUM_PLUS → PREMIUM_PRO.

주요 기능

구독 인식

서버는 프리미엄 등급에서만 사용할 수 있는 메서드를 알고 있으며, 호출이 머신을 떠나기 전에 차단하여 API 할당량을 절약합니다:

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

속도 제한 관리

  • 429 오류 발생 시 지수 백오프를 통한 자동 재시도.

  • Retry-After 준수(델타 초 및 RFC 7231 HTTP 날짜 모두 지원).

  • 느린 메서드에 대한 엔드포인트별 세마포어(예: /v1/analytics/turnover/stocks는 Ozon 측에서 1분당 1회 요청으로 엄격히 제한되며, 서버가 병렬 호출을 자동으로 큐에 넣습니다).

자동 페이지네이션

ozon_fetch_all은 Ozon이 사용하는 4가지 페이지네이션 패턴(offset/limit, cursor, last_id, page_number)을 모두 처리합니다. 또한 서버가 동일한 커서를 연속으로 두 번 반환하여 무한 루프에 빠지는 드문 경우를 감지하고 루프를 중단합니다.

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}

통합 오류 봉투

실패할 수 있는 모든 도구는 동일한 형태의 응답을 반환하므로, 에이전트나 하위 코드에서 쉽게 분기 처리할 수 있습니다:

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

카탈로그에 내장된 안전 분류

모든 메서드는 read, write, destructive 중 하나의 safety 필드를 가집니다. write는 confirm_write=True가 필요하며, destructive는 confirm_write=True와 i_understand_this_modifies_data=True가 모두 필요합니다. 스키마 추출기의 휴리스틱은 quirks.yaml의 43개 큐레이팅된 safety_warning 항목으로 강화되어, 에이전트가 데이터를 변경하기 전에 항상 명확한 경고를 확인하게 합니다.

API 사양 최신 유지

Ozon은 주기적으로 스웨거를 업데이트합니다. 동기화하려면:

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/

ozon_get_swagger_meta를 실행하여 번들된 스냅샷이 최신인지 확인하세요(CI는 스냅샷이 14일 이상 경과하면 빌드를 실패 처리합니다).

개발

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

지식(워크플로우, 예제, 특이 사항, 구독 재정의)을 추가하는 방법은 CONTRIBUTING.md를 참조하세요.

라이선스

MIT

Install Server
A
license - permissive license
A
quality
D
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

  • x402-mcp by x402node

    x402-mcpofficial

    x402node
    A
    license
    C
    quality
    C
    maintenance
    MCP server bringing 100+ x402-paid APIs to AI agents (Claude, Cursor, MCP-aware clients). Auto-discovers tools from CDP Bazaar; handles USDC micropayments on Base.
    100
    52
    1
    MIT

  • Avito MCP

    elchin92
    A
    license
    A
    quality
    A
    maintenance
    Universal 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.
    100
    152
    12
    MIT

  • wildberries-mcp

    shndo1337
    F
    license
    Not graded
    quality
    C
    maintenance
    MCP server that turns Wildberries marketplace into a toolkit for LLM agents, enabling product search, detailed card inspection, price history, reviews, and cross-product comparison.

  • mcp-ozon-seller

    woyaxnini
    A
    license
    A
    quality
    D
    maintenance
    MCP server for Ozon Seller API that enables AI clients to manage products, prices, stocks, orders, analytics, and finances on Ozon marketplace.
    26
    43
    6
    Inno Setup

View all related MCP servers

Related MCP Connectors

  • agentcentral

    Hosted Amazon Seller Central and Amazon Ads MCP server for Claude, ChatGPT, Cursor, and agents.

  • DepScope

    Package intelligence MCP for AI agents — 22 tools, 19 ecosystems, AGPL SDK, free.

  • Pangolinfo Amazon Data MCP

    Real-time Amazon, WIPO & PACER data for AI agents — 19 tools via the MCP protocol.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/PCDCK/ozon-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server