Skip to main content
Glama
deenesjakoruzh
PCDCK

ozon-mcp

by PCDCK
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

ozon-mcp

用于 Ozon 卖家和性能 API 的 MCP 服务器。 在几分钟内将任何 AI 代理连接到您的 Ozon 后台。

CI Python License MCP

ozon-mcp 是一个知识丰富的 MCP 服务器，它将整个 Ozon 卖家工具包转化为 15 个高杠杆工具。AI 代理（Claude、Cursor、Cline、Continue、Goose、Zed 等）可以用俄语或英语搜索 API，通过完全解析的 JSON Schema 深入研究 466 个方法中的任何一个，并使用内置的安全防护执行调用。支持订阅感知、所有 4 种游标样式的自动分页、针对 429 错误的重试/退避机制，以及 13 个即用型分析工作流。

关键事实： 466 个索引方法（420 个卖家 + 46 个性能），55 个部分，建模了 5 个订阅层级，自动遍历 38 个分页端点，对 43 个破坏性方法进行了双重门控，为典型的卖家场景策划了 13 个工作流。

快速入门

先决条件

安装

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/mcp.json，格式与上面的 Claude Desktop 配置相同。

Cursor

设置 → 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 → 设置 → MCP 服务器 → 添加：

{
  "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 — 获取您所有的产品

您： 使用 ozon_fetch_all 和 operation_id="ProductAPI_GetProductList" 来获取我所有的产品。

代理调用：

{
  "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 次请求/分钟 — 服务器的每个端点队列会为您处理此问题）以及如何解释 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 列表提醒代理与 marketing_seller_price（实际面向买家的价格）进行比较，而不仅仅是基础 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 以及同步风格工作流的推荐数据库模式。

工作流

类别

解决的问题

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

广告

性能 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。

主要功能

订阅感知

服务器知道哪些方法在 Premium 层级上受到限制，并在调用离开您的机器之前拒绝该调用 — 节省您的 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 次请求/分钟 — 服务器会自动对并行调用进行排队）。

自动分页

ozon_fetch_all 处理 Ozon 使用的所有四种分页模式：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
}

内置于目录中的安全分类

每个方法都带有 safety 字段 — read、write 或 destructive。写入需要 confirm_write=True；破坏性操作需要 confirm_write=True 且 i_understand_this_modifies_data=True。来自模式提取器的启发式方法通过 quirks.yaml 中的 43 个策划的 safety_warning 条目得到加强，因此代理在修改任何内容之前总是能看到清晰的提醒。

保持 API 规范更新

Ozon 会定期刷新其 swagger。同步方式：

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

运行 ozon_get_swagger_meta 以确认捆绑的快照是新鲜的（当快照超过 14 天时，CI 也会导致构建失败）。

开发

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