# mcp-ozon-seller

[![License: MIT + Commons Clause](https://img.shields.io/badge/license-MIT%20%2B%20Commons%20Clause-blue.svg)](./LICENSE)

MCP server for [Ozon Seller API](https://docs.ozon.ru/api/seller/) — Russia's largest marketplace.

Connect AI clients (Claude Desktop, Cursor, n8n) to your Ozon seller account: manage products, update prices and stocks, view orders, get analytics, monitor finances and returns.

> **First MCP server for Ozon Seller API.**

**26 tools · 7 groups · Two modes: local (stdio) + remote (HTTP)**

---

## Tools

### A. Account

| Tool | Description |
|------|-------------|
| `get_seller_info` | Verify credentials, get account info |

### B. Products

| Tool | Description |
|------|-------------|
| `list_products` | List products with status filters |
| `get_product` | Product card: attributes, status, images |
| `create_product` | Create new products (up to 100 at once) |
| `update_product` | Update product attributes and description |
| `archive_product` | Hide product from storefront |
| `unarchive_product` | Restore product to active sale |

### C. Prices & Stocks

| Tool | Description |
|------|-------------|
| `get_prices` | Current prices and price index |
| `update_prices` | Update prices (up to 1000 products at once) |
| `get_stocks` | Stock levels across all warehouses |
| `update_stocks` | Update FBS warehouse stocks |

### D. Orders

| Tool | Description |
|------|-------------|
| `list_fbo_orders` | List FBO orders |
| `get_fbo_order` | FBO order details |
| `list_fbs_orders` | List FBS orders |
| `get_fbs_order` | FBS order details |
| `get_fbs_awaiting` | FBS orders waiting to be shipped |

### E. Analytics

| Tool | Description |
|------|-------------|
| `get_analytics` | Sales, revenue, views, returns — any period |
| `get_warehouse_stocks` | Ozon warehouse stocks with turnover data |

### F. Finance

| Tool | Description |
|------|-------------|
| `get_finance_report` | Cash flow report for a period |
| `list_transactions` | Transactions: accruals, commissions, payouts |
| `get_transactions_totals` | Transaction summary totals |

### G. Returns & Rating

| Tool | Description |
|------|-------------|
| `list_fbo_returns` | FBO returns: items, reasons, amounts |
| `list_fbs_returns` | FBS returns: items, reasons, amounts |
| `get_seller_rating` | Seller quality index |
| `get_seller_rating_history` | Seller rating history over time |
| `list_warehouses` | Seller warehouses (IDs needed for stock updates) |

---

## Quick Start

### Mode 1: Local (stdio) — Claude Desktop / Cursor

**Step 1:** Get your API credentials
Ozon Seller → Settings → API Integrations → Seller API → Create key (role: **Admin**)

**Step 2:** Add to your Claude Desktop config:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ozon-seller": {
      "command": "npx",
      "args": ["-y", "@woyax/mcp-ozon-seller"],
      "env": {
        "OZON_CLIENT_ID": "123456",
        "OZON_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

**Step 3:** Restart Claude Desktop. Ask: *"Show my top 10 products by revenue for last week"*

---

### Mode 2: Remote (HTTP) — hosted on your VPS

**Start the server:**
```bash
MCP_PORT=3000 npx @woyax/mcp-ozon-seller --transport http
```

**Connect from any MCP client:**
```
http://your-server.com:3000/mcp?client_id=123456&api_key=your-api-key
```

Multiple users can connect simultaneously — credentials are passed per-request.

---

## n8n Integration

Add a custom MCP node with URL:
```
http://your-server.com:3000/mcp?client_id=CLIENT_ID&api_key=API_KEY
```

---

## Example Prompts

```
Show my revenue and orders for the last 7 days
```
```
List all products that are out of stock
```
```
Update the price for offer_id ABC-123 to 1990 rubles
```
```
Show all FBS orders that are waiting to be shipped
```
```
What's my current seller rating?
```
```
Show finance report for last month
```

---

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `OZON_CLIENT_ID` | **Yes** | Numeric seller ID from Ozon personal account |
| `OZON_API_KEY` | **Yes** | API key (UUID) from Ozon personal account |
| `MCP_TRANSPORT` | No | `stdio` (default) or `http` |
| `MCP_PORT` | No | Port for HTTP mode (default: `3000`) |

---

## API Credentials

1. Go to [Ozon Seller](https://seller.ozon.ru)
2. Settings → API Integrations → Seller API
3. Create new key with role **Admin** (required for all 26 tools)
4. Save `Client-Id` (numeric) and `Api-Key` (UUID)

---

## Rate Limits

Ozon API enforces rate limits. This server automatically retries on 429 errors with exponential backoff (1s → 2s → 4s).

⚠️ `get_warehouse_stocks` has stricter limits — avoid calling it in tight loops.

---

## Author & Support

Built by [Oleg Alekseev](https://github.com/woyaxnini) — ERP/AI integration architect.

- 📧 [woyaxnini@gmail.com](mailto:woyaxnini@gmail.com) · [woyax@yandex.com](mailto:woyax@yandex.com)
- 💬 Telegram: [@ale_oleg](https://t.me/ale_oleg) · Channel: [@woyax_ai](https://t.me/woyax_ai)
- 💬 MAX: [max.ru/id503610654564_biz](https://max.ru/id503610654564_biz)

Need help integrating AI agents with your ERP, CRM, or Ozon? Custom MCP servers, n8n workflows, AI automation — [contact me](mailto:woyaxnini@gmail.com).

---

## Woyax AI Stack — Corporate AI Suite for Russian Business

This package is part of **[Woyax AI Stack](https://github.com/woyaxnini)**: a collection of MCP servers and AI agents for business process automation in the Russian corporate environment.

| Component | What it does | Links |
|---|---|---|
| **[mcp-max-messenger](https://github.com/woyaxnini/mcp-max-messenger)** | AI integration with MAX messenger: notifications, approvals, bots | [Use cases](https://woyaxnini.github.io/mcp-max-messenger/) · [Article](https://spark.ru/user/268070/blog/317224/mcp-server-dlya-messendzhera-max-po-url-ndash-nashe-vsyo-karta-primenimosti) |
| **[mcp-chestnyi-znak](https://github.com/woyaxnini/mcp-chestnyi-znak)** | True API access for product labelling: marking codes, documents, balances | [Use cases](https://woyaxnini.github.io/mcp-chestnyi-znak/) |
| **[mcp-ozon-seller](https://github.com/woyaxnini/mcp-ozon-seller)** | Ozon store management: products, prices, orders, finance, analytics | [GitHub](https://github.com/woyaxnini/mcp-ozon-seller) |
| **[Woyax AI Process Auditor](https://spark.ru/user/268070/blog/310279/voyaks-analitik-ii-avtomatizatsii-kommercheskaya)** | Telegram bot that conducts structured interviews with employees and builds a company AI automation map | [Article](https://spark.ru/user/268070/blog/310279/voyaks-analitik-ii-avtomatizatsii-kommercheskaya) |

---

## License

MIT + Commons Clause © [Oleg Alekseev](https://github.com/woyaxnini)

Free to use for personal and corporate purposes. Selling as a hosted service requires author's permission. See [LICENSE](./LICENSE) for details.