ozon-mcp

MCP-Server für die Ozon Seller & Performance APIs. Verbinden Sie jeden KI-Agenten in wenigen Minuten mit Ihrem Ozon-Konto.

ozon-mcp ist ein wissensreicher MCP-Server, der das gesamte Ozon-Verkäufer-Toolkit in 15 leistungsstarke Tools verwandelt. KI-Agenten (Claude, Cursor, Cline, Continue, Goose, Zed, …) können die API auf Russisch oder Englisch durchsuchen, mit einem vollständig aufgelösten JSON-Schema in jede der 466 Methoden eintauchen und Aufrufe mit integrierten Sicherheitsvorkehrungen ausführen. Abonnement-bewusst, automatische Paginierung über alle 4 Cursor-Stile, Wiederholungsversuche/Back-off bei 429ern und 13 einsatzbereite analytische Workflows.

Wichtige Fakten: 466 indizierte Methoden (420 Seller + 46 Performance), 55 Abschnitte, 5 modellierte Abonnement-Stufen, 38 automatisch durchlaufene paginierte Endpunkte, 43 destruktive Methoden mit doppelter Absicherung, 13 kuratierte Workflows für typische Verkäufer-Szenarien.

Schnellstart

Voraussetzungen

• Python 3.12 oder 3.13

• uv Paketmanager — installieren mit curl -LsSf https://astral.sh/uv/install.sh | sh

• Ozon Seller API-Zugangsdaten (Client-Id + Api-Key) — erhältlich unter https://seller.ozon.ru/app/settings/api-keys

Installation

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

Überprüfung der Funktion

uv run ozon-mcp --help

Sie sollten die FastMCP-Nutzungszeile sehen. Der Server spricht das MCP-stdio-Protokoll — verweisen Sie jeden kompatiblen Client darauf (Anweisungen unten).

Related MCP server: Avito MCP

Verbindung mit Ihrem KI-Agenten

ozon-mcp verwendet den standardmäßigen MCP-stdio-Transport. Jedes der folgenden Beispiele stellt dieselben 15 Tools bereit — wählen Sie den Client, den Sie bereits verwenden.

Claude Desktop

Bearbeiten Sie: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder %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

Oder fügen Sie es zu ~/.claude/mcp.json mit der gleichen Struktur wie die Claude Desktop-Konfiguration oben hinzu.

Cursor

Einstellungen → MCP → Neuen MCP-Server hinzufügen, oder bearbeiten Sie ~/.cursor/mcp.json:

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

Windsurf

Bearbeiten Sie ~/.codeium/windsurf/mcp_config.json:

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

Cline (VS Code Erweiterung)

Cline → Einstellungen → MCP-Server → Hinzufügen:

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

Continue.dev

Bearbeiten Sie ~/.continue/config.json:

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

Goose, Zed oder ein anderer MCP-Client

Jeder Client, der MCP-stdio spricht, funktioniert. Generische Konfiguration:

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

Durchsuchen Sie die offizielle MCP-Client-Liste unter https://modelcontextprotocol.io/clients.

Nutzungsbeispiele

Alle folgenden Beispiele zeigen realistische Antworten, die aus tests/fixtures/responses/ kopiert wurden — anonymisierte Identifikatoren (99000001, TEST-SKU-001), aber echte Struktur.

Beispiel 1 — Alle Produkte abrufen

Sie: Verwenden Sie ozon_fetch_all mit operation_id="ProductAPI_GetProductList" um alle meine Produkte abzurufen.

Der Agent ruft auf:

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

Der Server durchläuft automatisch den last_id-Cursor und gibt zurück:

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

Beispiel 2 — Produkte finden, bei denen das Risiko eines Lagerbestandsausfalls besteht

Sie: Führen Sie den oos_risk_analysis Workflow für mein Konto aus.

Der Agent prüft zuerst den Workflow:

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

→ weist den Agenten an, AnalyticsAPI_StocksTurnover aufzurufen (ratenbegrenzt auf 1 Anfr./Min. — die Warteschlange des Servers pro Endpunkt erledigt das für Sie) und wie turnover_grade zu interpretieren ist. Der Aufruf gibt zurück:

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

Das interpret-Feld des Workflows weist den Agenten an, SKUs zu markieren, bei denen idc < 14 oder turnover_grade ∈ {DEFICIT, NO_SALES} gilt, und diese sortiert nach idc asc anzuzeigen.

Beispiel 3 — Vollständiger Gesundheitscheck des Kontos

Sie: Überprüfen Sie den Status meines Ozon-Kontos mit dem cabinet_health_check Workflow.

Der Workflow weist den Agenten an, drei Endpunkte parallel zu lesen — RatingAPI_RatingSummaryV1, SellerAPI_SellerInfo, AverageDeliveryTimeSummary. Der erste Aufruf gibt zurück:

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

Beispiel 4 — Analyse der Produktpreisgestaltung

Sie: Welche meiner Produkte haben einen roten Preisindex?

Der Agent führt den pricing_analysis Workflow aus und prüft das Feld price_indexes.color_index bei jedem Artikel:

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

Die common_mistakes-Liste des Workflows erinnert den Agenten daran, mit marketing_seller_price (dem tatsächlichen Preis für den Käufer) zu vergleichen, nicht nur mit dem Basispreis price.

Beispiel 5 — Inhaltsprüfung

Sie: Finden Sie Produkte mit niedriger Inhaltsbewertung und sagen Sie mir, was ich verbessern kann.

Der Agent führt content_audit aus, erhält Bewertungen pro SKU + die Liste der Attribute, die die Punktzahl erhöhen würden:

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

Der Workflow teilt dem Agenten mit, dass eine Steigerung von +10 beim rating das Suchranking messbar verbessert — das Ausfüllen dieser zwei Attribute ist also etwa 4 Punkte wert.

Verfügbare Tools (15)

Fertige Workflows (13)

Workflows sind kuratierte Schritt-für-Schritt-Rezepte. Verwenden Sie ozon_get_workflow("name"), um den vollständigen Plan abzurufen, einschließlich interpret, when_to_use, common_mistakes und dem empfohlenen DB-Schema für Workflows im Sync-Stil.

API-Abdeckung

Modellierte Abonnement-Stufen (niedrig → hoch): LITE → STANDARD → PREMIUM → PREMIUM_PLUS → PREMIUM_PRO.

Hauptmerkmale

Abonnement-bewusst

Der Server weiß, welche Methoden auf Premium-Stufen beschränkt sind, und verweigert den Aufruf, bevor er Ihren Computer verlässt — das spart Ihr API-Kontingent:

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

Ratenbegrenzungs-Management

• Automatische Wiederholung mit exponentiellem Back-off bei 429.

• Berücksichtigt Retry-After (sowohl Delta-Sekunden als auch RFC 7231 HTTP-Datum).

• Semaphor pro Endpunkt für langsame Methoden (z. B. /v1/analytics/turnover/stocks ist auf der Ozon-Seite hart auf 1 Anfr./Min. begrenzt — der Server reiht parallele Aufrufe automatisch ein).

Automatische Paginierung

ozon_fetch_all handhabt alle vier Paginierungsmuster, die Ozon verwendet: offset/limit, cursor, last_id, page_number. Es erkennt auch den seltenen Fall, in dem der Server denselben Cursor zweimal hintereinander zurückgibt, und bricht die Schleife ab, anstatt ewig zu drehen.

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}

Einheitliche Fehler-Umschlagstruktur

Jedes Tool, das fehlschlagen kann, gibt die gleiche Struktur zurück — einfach zu verzweigen in jedem Agenten oder nachgelagerten Code:

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

Sicherheitsklassifizierung im Katalog integriert

Jede Methode trägt ein safety-Feld — read, write oder destructive. Schreiben erfordert confirm_write=True; destruktive Aktionen erfordern sowohl confirm_write=True ALS AUCH i_understand_this_modifies_data=True. Heuristiken aus dem Schema-Extraktor werden durch 43 kuratierte safety_warning-Einträge in quirks.yaml verstärkt, sodass der Agent immer eine klare Erinnerung sieht, bevor er etwas ändert.

API-Spezifikationen auf dem neuesten Stand halten

Ozon aktualisiert sein Swagger regelmäßig. Zum Synchronisieren:

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/

Führen Sie ozon_get_swagger_meta aus, um zu bestätigen, dass der gebündelte Snapshot aktuell ist (die CI lässt den Build ebenfalls fehlschlagen, wenn der Snapshot älter als 14 Tage ist).

Entwicklung

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

Siehe CONTRIBUTING.md für Informationen zum Hinzufügen von Wissen (Workflows, Beispiele, Besonderheiten, Abonnement-Überschreibungen).

Lizenz

MIT