OZON MCP

Open-Source-MCP-Server für Ozon-Verkäufer, mit integrierter chinesischer Wissensdatenbank für den Betrieb (42 Lektionen) und 466 API-Methoden. So können KI-Agenten Betriebserfahrung abrufen, Seller/Performance-APIs aufrufen und echte Geschäftsvorgänge ausführen.

Inhaltsverzeichnis

• Projektübersicht

• Kernfunktionen

• Anwendungsszenarien

• Systemarchitektur

• Projektstruktur

• Systemvoraussetzungen

• Schnellstart

• Umgebungsvariablen

• MCP-Client-Konfiguration

• Aufrufbeispiele

• Entwicklung und Tests

• Sicherheitshinweise

• Häufig gestellte Fragen

• Lizenz

• Haftungsausschluss

Projektübersicht

OZON MCP ist ein wissensbasierter MCP-Server, der auf dem Model Context Protocol basiert. Er kapselt die vollständige API-Dokumentation, Parameterschemata, Rate-Limit-Regeln und Geschäftsworkflows der Ozon Seller API und Performance API in standardisierte MCP-Tools, sodass KI-Agenten wie Claude, Cursor und Codex Ozon-APIs direkt durchsuchen, verstehen und aufrufen können.

Welches Problem wird gelöst

Die Ozon-Open-Plattform verfügt über zwei API-Systeme (Seller + Performance) mit insgesamt über 460 Schnittstellen, verteilt auf 55 Geschäftsmodule. Das manuelle Nachschlagen von Dokumentationen, das Zusammenstellen von Anfragen sowie die Verarbeitung von Paginierung und Rate-Limits ist sehr zeitaufwendig.

OZON MCP macht KI-Agenten zu deinem Ozon-Betriebsassistenten:

• Der Agent kann API-Methoden in Chinesisch oder Russisch durchsuchen und die benötigte Schnittstelle finden

• Jede Methode liefert ein vollständig geparstes JSON-Schema, einschließlich Anforderungsparametern, Antwortstruktur, Rate-Limit-Regeln und bekannten Fallstricken

• Bei Schreiboperationen gibt es mehrschichtige Sicherheitswächter, die Fehlbedienungen verhindern

• Unterstützt automatische Paginierung für die Verarbeitung großer Datenmengen

• Integriert 13 ausgewählte Geschäftsworkflows für Szenarien wie Fehlbestandsanalyse, Preisdiagnose und Shop-Health-Check

Für wen ist das geeignet

• Ozon-Verkäufer, die KI-Unterstützung für die tägliche Betriebsanalyse wünschen

• Entwickler von Tools für den grenzüberschreitenden E-Commerce, die Ozon-Funktionen in Agenten integrieren möchten

• Entwickler, die sich für das MCP-Protokoll interessieren und praktische Umsetzungsbeispiele kennenlernen möchten

Kernfunktionen

API-Erkennung und Navigation

Geschäftsworkflows

13 ausgewählte Workflows, die folgende Geschäftskategorien abdecken:

Jeder Workflow enthält: Abfolge der Operationsschritte, Paginierungs-/Parallelitätshinweise, empfohlene Datenbankschemata, bekannte Fallstricke und Anleitung zur Ergebnisinterpretation.

Sichere Ausführung

Referenzinformationen

Abonnementberechtigungen

Hinweis: Die aktuelle Version ist ein Wissensserver – auch ohne API-Anmeldedaten funktionieren alle Erkennungs-, Such-, Referenz- und Workflow-Tools normal. Anmeldedaten werden nur benötigt, wenn echte API-Aufrufe ausgeführt werden sollen.

API-Methodenübersicht

Das Projekt enthält einen vollständigen chinesischen Katalog von 466 Ozon-API-Methoden (methods_catalog.md), der alle Bereiche des Ozon-Verkäufergeschäfts abdeckt:

Nach der Integration kann der Agent auf Chinesisch suchen (z. B. „Bestellliste abfragen", „Bestand massenhaft aktualisieren") und mithilfe der kartenartigen chinesischen Beschreibungen schnell die richtige API finden und aufrufen. Jede Methode ist mit HTTP-Methode, Schnittstellenpfad, Sicherheitsstufe und Abonnementanforderung gekennzeichnet, sodass der Agent direkt beurteilen kann, ob eine Bestätigung für Schreiboperationen oder eine höhere Abonnementstufe erforderlich ist.

Chinesische Ozon-Betriebswissensdatenbank

Das Projekt enthält eine vollständige chinesische Ozon-Betriebswissensdatenbank, basierend auf 42 Ozon-E-Commerce-Lektionen, mit 610 durchsuchbaren Wissensfragmenten. Der Agent kann in chinesischer natürlicher Sprache suchen und schnell Betriebserfahrung, Arbeitsabläufe und Tipps zur Fehlervermeidung finden.

Überblick über die Wissensdatenbank

Abgedeckte Themen

Die Wissensdatenbank deckt die gesamte Kette von der Shop-Eröffnung bis zum After-Sales-Service für Ozon-Verkäufer ab:

• Plattform-Geschäftsmodelle (Mitverkauf, selektive Bepflanzung, Massenbepflanzung, Dropshipping)

• Die vier Fulfillment-Modelle FBS, FBO, FBP, rFBS

• Shop-Registrierung und internationale Versandkostenberechnung

• Lagereinrichtung und Logistikkonfiguration

• Produktauswahlmethoden und Aufbau eines Produktauswahl-Pools

• Überprüfung von Produktgewicht und -maßen

• Detaillierte Erläuterung des Verkäufer-Backends

• Produktkarten-Optimierung und Erstellung von Hauptbildern

• Preisstrategien und Gewinnmargenberechnung

• Werbeaktionen und Werbekampagnen

• Auftragsabwicklung und Versandprozesse

• Retourenbearbeitung und Sonderbestellungen

• Betriebsrisiken und Schutz vor Shop-Sperrungen

MCP-Tools für Betriebswissen

Empfohlene Aufrufreihenfolge: Zuerst suchen → chunk_id auswählen → vollständigen Beleg lesen → Antwort formulieren.

Agent-Aufrufablauf

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

Aufrufbeispiele

„Sollte ein Anfänger zuerst Mitverkauf oder selektive Bepflanzung machen?"

Der Agent ruft zuerst ozon_search_operations_knowledge({"query": "新手先做跟卖还是精铺"}) auf, ruft nach Erhalt relevanter Fragmente ozon_get_operations_knowledge auf, um den vollständigen Beleg zu lesen, und beantwortet auf Basis der Kursinhalte die Vor- und Nachteile sowie die Anwendungsbedingungen beider Modelle.

„Was ist ein Spediteur, und wie läuft der vollständige rFBS-Versandprozess ab?"

Der Agent sucht nach "货代 rFBS 发货流程", erhält relevante Wissensfragmente aus Lektion 01 und erklärt anhand der Kursinhalte das Spediteur-Konzept und die vollständige rFBS-Kette von der Auftragserstellung bis zur Unterschrift.

„Wie sollte man bei selektiver Bepflanzung Differenzierung betreiben?"

Der Agent sucht nach "精铺差异化", erhält aus Lektion 02 den vollständigen Beleg für Differenzierungsstrategien bei der Produktauswahl und beantwortet die Frage einschließlich Produktkarten-Optimierung, Hauptbild-Differenzierung und Preisstrategien.

„Wie sollte man Ozon-Lager und -Logistik einrichten?"

Der Agent sucht nach "仓库物流设置" und erhält aus Lektion 06 die detaillierten Schritte und Hinweise zur Lagerkonfiguration.

„Wie sollte man das Gewicht vor der Produktveröffentlichung überprüfen?"

Der Agent sucht nach "上架前核实重量" und erhält aus Lektion 07 die Methoden zur Gewichtsüberprüfung und häufige Fallstricke.

„Was sollte man zuerst prüfen, wenn ein Produkt keine Sichtbarkeit hat?"

Der Agent sucht nach "商品没有曝光" und erhält relevante Fragmente zur Diagnose von Produktkarte, Preisgestaltung und Suchranking.

Antwortgrenzen

Wichtiger Hinweis:

• Kursinhalte sind Zusammenfassungen von Betriebserfahrung und nicht gleichzusetzen mit den aktuellen offiziellen Ozon-Regeln

• Provisionen, Gebühren, Lieferzeiten, Verkaufsverbote, Strafen, Werbe- und Retourenrichtlinien können sich jederzeit ändern

• Bei Fragmenten mit verification_required=true muss der Kunde aufgefordert werden, die aktuellen offiziellen Unterlagen zu überprüfen

• Bei Daten zu echten Kunden-Shops, Bestellungen, Lagerbeständen, Produkten, Finanzen oder Werbung muss die echte Ozon-API aufgerufen werden

• Inhalte, die nicht in der Wissensdatenbank abgedeckt sind, dürfen nicht erfunden werden

Aktualisieren der Wissensdatenbank

Bei zukünftigen Aktualisierungen des Betriebswissens die folgenden Dateien ersetzen:

• 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

Anschließend die Validierung ausführen:

uv run python scripts/validate_operations_knowledge.py
uv run pytest

Anwendungsszenarien

Szenario 1: Ausstehende Bestellungen abfragen

„Hilf mir, alle Bestellungen mit Status 'ausstehend' abzurufen"

Der Agent sucht zuerst mit ozon_search_methods nach „order list" oder „订单列表", findet OrderAPI_GetOrderList, prüft dann mit ozon_describe_method die Parameterstruktur und ruft schließlich über ozon_fetch_all alle Bestellungen mit Paginierung ab.

Szenario 2: Fehlbestandsrisiko-Prüfung

„Führe den Workflow zur Fehlbestandsrisiko-Analyse aus und prüfe, welche SKUs möglicherweise ausverkauft sind"

Der Agent führt ozon_get_workflow({"name": "oos_risk_analysis"}) aus, ruft schrittweise AnalyticsAPI_StocksTurnover auf und markiert Risiko-SKUs gemäß den im Workflow integrierten Interpretationsregeln.

Szenario 3: Shop-Health-Check

„Prüfe den Gesamtzustand meines Shops"

Der Agent führt ozon_get_workflow({"name": "cabinet_health_check"}) aus, ruft parallel die drei Schnittstellen für Bewertung, Shop-Informationen und Lieferzeit auf und fasst alle Kennzahlen und Status zusammen.

Szenario 4: Massenexport von Produktinformationen

„Rufe die Basisinformationen aller aktiven Produkte ab"

Der Agent verwendet ozon_fetch_all mit ProductAPI_GetProductList, durchläuft automatisch die last_id-Paginierung und gibt die vollständige Produktliste zurück.

Szenario 5: Unklarheit über die Verwendung einer API

„Gibt es bei Ozon eine Schnittstelle zur Abfrage des Lagerbestands? Wie fülle ich die Parameter aus?"

Der Agent findet mit ozon_search_methods({"query": "warehouse stock"}) die entsprechende Methode, ruft dann mit ozon_describe_method das vollständige Parameterschema und Aufrufbeispiele ab und hilft dir anschließend beim Zusammenstellen der Anforderungsparameter.

Systemarchitektur

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

Erläuterung der Kernmodule:

• Wissensschicht: Lädt beim Start die vollständigen Definitionen von 466 Methoden aus integrierten Swagger-Dateien und der YAML-Wissensdatenbank

• Suchindex: Volltextsuchmaschine basierend auf BM25, unterstützt chinesische und russische Tokenisierung sowie Feldgewichtung

• Methodengraph: Automatisch aufgebautes Beziehungsnetzwerk von Methoden basierend auf Dokumentationslinks und Workflows

• Rate-Limit-Verwaltung: Rate-Limits auf per-API-Ebene, mit automatischer Warteschlange und Backoff-Retry

• Sicherheitswächter: Dreistufige Validierung – Sicherheitsstufe (nur lesen/schreiben/destruktiv) → Abonnementberechtigung → JSON-Schema-Validierung

Projektstruktur

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

Systemvoraussetzungen

Ozon-API-Berechtigungen

• Seller API: Client-Id und Api-Key müssen im Ozon-Backend generiert werden

• Performance API: Client ID und Client Secret müssen beantragt werden

Schnellstart

Methode 1: Mit uv (empfohlen)

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

# 安装依赖
uv sync

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

Wenn die Hilfeinformationen angezeigt werden, war die Installation erfolgreich. Jetzt kann die Verbindung zu einem MCP-Client hergestellt werden (siehe MCP-Client-Konfiguration).

Methode 2: Mit 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

Das Docker-Image enthält keine Anmeldedaten; diese müssen über -e oder --env-file übergeben werden.

Umgebungsvariablen

Alle Anmeldedaten werden mit pydantic.SecretStr geschützt und werden nicht versehentlich ausgegeben oder in Protokollen aufgezeichnet.

Konfigurationsbeispiel siehe .env.example.

MCP-Client-Konfiguration

OZON MCP verwendet das MCP-stdio-Protokoll. Die folgende Konfiguration gilt für verschiedene MCP-Clients.

Claude Desktop

Konfigurationsdatei bearbeiten:

• 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-Pfade verwenden Schrägstriche oder doppelte Backslashes, z. B. D:/ozon-mcp oder D:\\ozon-mcp.

Claude Code (CLI)

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

Oder ~/.claude/mcp.json manuell bearbeiten:

{
  "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, oder ~/.cursor/mcp.json bearbeiten:

{
  "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 bearbeiten:

{
  "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 bearbeiten:

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

Andere MCP-Clients

Jeder Client, der das MCP-stdio-Protokoll unterstützt, kann angebunden werden. Allgemeine Konfiguration:

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

Weitere Clients findest du in der offiziellen MCP-Client-Liste.

Aufrufbeispiele

Die folgenden Beispiele zeigen die Interaktion mit OZON MCP über einen KI-Agenten in natürlicher Sprache.

Abfragekategorie

Du: Liste die Module der Ozon Seller API auf

Der Agent ruft ozon_list_sections auf und gibt die 55 Module mit ihrer Methodenanzahl zurück.

Du: Suche alle Schnittstellen, die mit „Bestellung" zu tun haben

Der Agent ruft ozon_search_methods({"query": "订单"}) auf und gibt die passenden Ergebnisse mit Bewertung zurück.

Du: Zeige die vollständige Dokumentation von OrderAPI_GetOrderList

Der Agent ruft ozon_describe_method({"operation_id": "OrderAPI_GetOrderList"}) auf und gibt das vollständige JSON-Schema, Rate-Limit-Regeln und Aufrufbeispiele zurück.

Analyse-Kategorie

Du: Analysiere den Gesamtzustand meines Shops

Der Agent führt ozon_get_workflow({"name": "cabinet_health_check"}) aus, um die Workflow-Schritte zu erhalten, ruft dann schrittweise Schnittstellen wie Bewertung und Shop-Informationen auf und fasst die Analyseergebnisse zusammen.

Du: Welche Produkte haben ein Fehlbestandsrisiko

Der Agent führt ozon_get_workflow({"name": "oos_risk_analysis"}) aus, ruft die Lagerumschlags-Schnittstelle auf und markiert SKUs mit den Status DEFICIT und NO_SALES gemäß den im Workflow integrierten Interpretationsregeln.

Massenkategorie

Du: Rufe alle aktiven Produkte ab

Der Agent ruft ozon_fetch_all({"operation_id": "ProductAPI_GetProductList", "params": {"filter": {"visibility": "ALL"}}}) auf, durchläuft automatisch die Paginierung und gibt die vollständige Produktliste zurück.

Fehlerbehebungskategorie

Du: Beim Aufruf der Produktlistenschnittstelle ist ein Fehler aufgetreten, Fehlercode 429

Der Agent ruft ozon_get_error_catalog({"code": "429"}) auf, um die Erklärung und Lösung für den Rate-Limit-Fehler abzurufen, und verwendet gleichzeitig ozon_get_rate_limits({"operation_id": "ProductAPI_GetProductList"}), um die spezifischen Rate-Limit-Regeln dieser Schnittstelle anzuzeigen.

Entwicklung und Tests

Entwicklungabhängigkeiten installieren

uv sync --dev

Tests ausführen

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

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

Code-Prüfung

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

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

Lokalen Dienst starten

# 仅知识模式（无需凭据）
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 .

Sicherheitshinweise

• .env-Dateien nicht committen. Alle Anmeldedaten werden über Umgebungsvariablen übergeben; .env ist in .gitignore aufgenommen

• Vollständige Anmeldedaten nicht in Protokollen aufzeichnen. Alle Anmeldedatenfelder sind mit SecretStr geschützt; repr() und print() geben die tatsächlichen Werte nicht preis

• Minimalberechtigungen verwenden. Es wird empfohlen, für den MCP-Server separate Ozon-API-Schlüssel zu erstellen und nur die erforderlichen Berechtigungen zu erteilen

• Schlüssel regelmäßig rotieren. Es wird empfohlen, die API-Schlüssel regelmäßig im Ozon-Backend zu aktualisieren

• Schreiboperationen erfordern menschliche Bestätigung. Alle write- und destructive-Operationen erfordern einen zusätzlichen Bestätigungsparameter

• In vertrauenswürdiger Umgebung ausführen. Es wird empfohlen, lokal oder auf einem vertrauenswürdigen Server auszuführen und nicht im öffentlichen Netzwerk zu exponieren

• Plattformregeln vor der Verwendung prüfen. Die Rate-Limit-Regeln, Berechtigungsanforderungen und Gebührenstrategien der Ozon-API können sich ändern

Häufig gestellte Fragen

MCP-Client findet den Dienst nicht

Stelle sicher, dass uv installiert und im PATH ist:

uv --version

uv-Befehl existiert nicht

uv installieren:

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

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

Umgebungsvariablen werden nicht wirksam

Stelle sicher, dass die Variablennamen das Präfix OZON_ verwenden und korrekt gesetzt sind. Mit dem folgenden Befehl testen:

OZON_LOG_LEVEL=DEBUG uv run ozon-mcp --help

Ozon-API gibt 401 oder 403 zurück

Prüfe, ob OZON_CLIENT_ID und OZON_API_KEY korrekt sind, und stelle sicher, dass der Schlüssel nicht abgelaufen ist.

Anforderungsratenlimit (429)

Der Server verfügt bereits über automatische Retry- und Backoff-Mechanismen. Wenn weiterhin 429 auftritt, kann die Häufigkeit paralleler Anforderungen reduziert werden.

Docker-Start fehlgeschlagen

Stelle sicher, dass Docker installiert ist und der Build-Befehl im Projektstammverzeichnis ausgeführt wird:

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

Windows-Pfadprobleme

Pfade in der MCP-Client-Konfiguration verwenden Schrägstriche oder doppelte Backslashes:

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

Konfiguration mehrerer Shops

In der aktuellen Version entspricht ein MCP-Server-Prozess einem Ozon-Konto. Für mehrere Shops müssen mehrere Server-Instanzen gestartet werden, jeweils mit unterschiedlichen Umgebungsvariablen.

Wissensdatenbank nicht verfügbar (knowledge_unavailable)

Wenn die Wissensdatenbank beim Start nicht geladen werden kann (z. B. aufgrund beschädigter oder fehlender Datendateien), sind die drei Wissenswerkzeuge weiterhin vorhanden, geben jedoch bei Aufruf einen einheitlichen Fehler zurück:

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

Feldbeschreibung:

Hinweis: Wenn die Wissensdatenbank nicht verfügbar ist, funktionieren die API-Wissensebene und andere Werkzeuge weiterhin normal; nur die Betriebswissensabfragefunktion ist betroffen. Nach der Wiederherstellung der Wissensdatenbankdatei und einem Neustart wird der Betrieb automatisch fortgesetzt.

Lizenz

Dieses Projekt ist unter der MIT License lizenziert.

Haftungsausschluss

• Dieses Projekt ist kein offizielles Ozon-Projekt und steht in keiner Verbindung zu Ozon.

• Die Schnittstellen, Begrenzungsregeln, Provisionsrichtlinien und Berechtigungsanforderungen der Ozon-API können sich jederzeit ändern.

• Benutzer müssen die Nutzungsbedingungen und geltenden Gesetze und Vorschriften der Ozon-Plattform eigenständig einhalten.

• Bei Schreib- und Geldtransaktionen wird empfohlen, vor der Ausführung eine manuelle Überprüfung durchzuführen.

• Dieses Projekt übernimmt keine Haftung für Verluste, die durch die Nutzung dieser Software entstehen.