Ozon MCP Server

Run your Ozon stores straight from a chat with an AI assistant: prices, promos,

advertising, orders, returns, reviews, finances — 151 tools on top of the Ozon

Seller API and Performance API (Ozon is Russia's largest marketplace; the Seller

API covers catalogue and operations, the Performance API covers paid ads).

Built for sellers who run more than one store: every call takes a `shop_id`,

and API keys stay encrypted on your own server — nothing leaves it.

What sets it apart from other Ozon MCP servers: it covers advertising as well as

the Seller API, and its built-in diagnostics tell you which Ozon endpoints broke

before your assistant runs into them.

Selling on Wildberries too? There is the same server for WB —

wb-mcp-server.

This is the author's own working tool: more than five months of daily use, around

twenty seller accounts, 151 tools. It gets updated when he needs it updated — see

Updates and support for what that means for you.

> The per-client installation guides in `docs/` are currently Russian only.

> The configuration in them is ready-to-paste JSON, which reads the same in any

> language: file paths, the URL `http://localhost:8000/sse`, and the header

> `Authorization: Bearer `.

You: Which of my products is Ozon planning to pull into a promo?
You: Show ad campaign spend for the week and stop the ones burning money.
You: Which products have a worse price index than their competitors?
You: Reply with a thank-you to every new 5-star review.

What it does

FBO and FBS are Ozon's fulfilment models: FBO ships from Ozon's warehouses,

FBS from yours, rFBS is FBS with your own delivery.

The full numbered list, with a description and the parameters of every tool, is in

**docs/tools.md**. It is generated from `ozon_mcp/server.py` (the

`TOOLS` constant) — the same thing `tools/list` returns to any MCP client.

Quick start

Option 1: one command, no Docker

The server speaks stdio, which is how Claude Desktop, Cursor, VS Code and other

MCP clients connect to it. Nothing to build:

uvx ozon-mcp-server

Or via pip:

pip install ozon-mcp-server
ozon-mcp

Client configuration (for example `claude_desktop_config.json`):

{
  "mcpServers": {
    "ozon": {
      "command": "uvx",
      "args": ["ozon-mcp-server"],
      "env": {
        "OZON_CLIENT_ID": "your Client-Id",
        "OZON_API_KEY": "your API key",
        "DATA_DIR": "~/.ozon-mcp"
      }
    }
  }
}

Point `DATA_DIR` at any writable directory — it holds stores, keys and statistics.

The default is `/data`, which is the path used inside Docker.

Option 2: Docker with the web dashboard

Use this if you want the dashboard, Ozon API diagnostics and browser-based store

management. Five commands:

git clone https://github.com/DeviceIngineering/ozon-mcp-server.git
cd ozon-mcp-server
cp .env.example .env               # fine as-is for a trusted local network
docker compose up -d --build       # builds the image, serves on port 8000
open http://localhost:8000/shops   # add a store and its Ozon API keys

What each step does:

• `.env` — every variable is optional. Store keys are easier to enter in the web

UI than here. The one thing worth setting up front, if the server is reachable

by anyone but you, is `MCP_AUTH_TOKEN` (generate one with `openssl rand -hex 32`).

• `docker compose up -d --build` — builds the image from the `Dockerfile`, maps

port `8000:8000` and creates the `ozon_data` volume for stores, keys, call

statistics and diagnostics history. `restart: unless-stopped` brings the

container back up after a reboot.

• `/shops` — the add-store form: `shop_id` (the handle you'll use in chat), a

display name, Client-Id + Api-Key for the Seller API, and Client-Id +

Client-Secret for the Performance API. The "Проверить" (Test) button makes a

live request to Ozon and tells you whether the keys were accepted.

Once it's running:

Note that the web UI is in Russian.

To stop: `docker compose down` (the data stays in the `ozon_data` volume).

Logs: `docker compose logs -f`.

Without Docker

python3 -m venv .venv && source .venv/bin/activate
pip install .
DATA_DIR=./data PORT=8000 ozon-mcp-web

`DATA_DIR` defaults to `/data`, so when running locally be sure to point it at a

directory you can write to.

Installing into clients

The transport is SSE at `http://:8000/sse`. SSE support differs between

clients: some speak it directly, others need the `mcp-remote` bridge. There is one

guide per client, with config paths for macOS, Linux and Windows and ready-made

JSON — in Russian, but the JSON blocks are language-neutral:

The shortest example, Claude Code:

claude mcp add --transport sse ozon http://localhost:8000/sse \
  --header "Authorization: Bearer "

Client summary and the bridge reference: docs/README.md.

Multi-store and security

Stores are added in the web UI, and every tool takes a required `shop_id`;

`ozon_list_shops` tells you which ones exist. In chat it looks like this:

"show me the stock in store `alpha`".

The real gain is not the switching itself but that **a strategy is written once and

rolled out to every account**: a rule about prices, review replies or ad bids

applies to all stores at once — no logging in and out of seller accounts, no

copying keys between client configs.

The price you pay is a shared IP. Every account talks to Ozon from one address:

the server the MCP runs on. Ozon's rate limits are counted per address among other

things, so the more accounts you have and the harder your strategies work them, the

closer the combined traffic gets to the threshold where throttling or a block kicks in.

• there is no limit on the number of stores in the code;
• the real ceiling comes from Ozon's per-IP limits, not from this server;
• around twenty accounts is the author's own estimate of where the traffic still

stays in the safe zone;

• beyond that, spread the stores across several servers with different addresses.

You can see the limit approaching, and the place to see it is the web UI: failed

pings and diagnostics warnings start piling up, and the error share in the call

statistics jumps. The dashboard also tells the two cases apart — mass throttling

looks like many tools degrading at once, a broken endpoint like a single one.

How keys are stored:

• on first use, `.encryption_key` — a Fernet key — is created in `DATA_DIR`;
• store keys are encrypted with it and kept in `DATA_DIR/shops.json`;
• the web UI shows keys masked (`abc***xyz`), and saving a masked value does not

overwrite the real one;

• under Docker all of this lives in the `ozon_data` volume. To move to another

machine, copy the whole volume — otherwise you lose the encryption key

(see DEPLOY.md, Russian).

What to know about access:

• `MCP_AUTH_TOKEN` protects only `/sse`. Pass it as the

`Authorization: Bearer …` header or as a `?token=…` query parameter.

• An empty `MCP_AUTH_TOKEN` means no authentication at all. Only acceptable on a

trusted network.

• The web UI (`/`, `/shops`, `/diagnostics`) and `/api/*` are not behind the

token: anyone who can reach the port sees the dashboard and can add stores.

• Do not expose port 8000 to the internet directly. For remote access use

Tailscale or a VPN.

• The server does not terminate HTTPS. If you need TLS from outside, put a reverse

proxy in front.

The web UI: every call is visible

With a typical MCP server, calls vanish into the void: the assistant did

something, but what exactly, how long it took and what error it hit is known only

to the assistant. Here every call gets a line in the log, and every broken tool

gets a marker on the dashboard. For a tool that moves real money in a store, that

is not decoration — it is the condition for trusting it.

The call statistics and check history are not synthetic: they come from more than

five months of daily use across roughly twenty seller accounts. The list of caught

Ozon API changes in the limitations section comes from the same place — it was

read off the degradation log, not copied from the documentation.

Dashboard `/`

The screenshot is at the top of this page.

• Four counters at the top: total calls, calls today, errors, and average call

duration in milliseconds.

• Top 10 tools: call count, average duration, and how many of those calls failed.
• A feed of the last 50 calls: timestamp, `shop_id`, tool name, duration, success

or failure, and the error text.

• A per-store filter (`/?shop=alpha`) — the same figures for a single account.
• Two banners surface at the top: degraded tools, and "the last Ozon API check

found problems".

Stores `/shops`

Accounts are added and removed right in the browser, with no file editing and no

container restart. The "Проверить" (Test) button makes a live request to both APIs

(`POST /api/shops/{shop_id}/test`), so keys are verified when you add them rather

than during the first real call in the middle of a task. Tokens are encrypted with

Fernet, the encryption key lives in `DATA_DIR/.encryption_key`, and the UI shows

keys masked.

Diagnostics `/diagnostics`

*(the screenshot shows a demo store with deliberately invalid keys, which is why

every probe is red)*

• Per store: whether keys are set, Ozon host availability, 12 Seller API category

probes, and a Performance API key check.

• A background check every `HEALTH_CHECK_INTERVAL_MIN` minutes (30 by default,

`0` disables it), plus a "Проверить сейчас" (Check now) button for an immediate

run (`POST /api/diagnostics/run`).

• Check history: time, store, status, number of failed pings, number of failed

probes, and the warning texts. The UI shows the last 30 entries; up to 1000 are

kept in the database with automatic rotation.

• The same data is available from chat through the `ozon_diagnostics` tool.

Degradation detector

The server notices on its own that Ozon broke or switched off an endpoint — not

from the documentation and not from work that failed, but from its own statistics.

A tool whose last three calls in a row failed while earlier calls succeeded lands

in the degradation list, which shows the tool name, the time of the last successful

call, the number of consecutive errors, and the text of the latest one. On the

dashboard that is a red banner; on the diagnostics page, a table.

What this buys you: a change on Ozon's side becomes visible the day it happens,

not a week later when you discover prices haven't been updating. The same list is

available from chat via `ozon_degradations`.

JSON for external monitoring

All of the above can be scraped programmatically, not just looked at:

That is enough to wire the server into Zabbix, Uptime Kuma, or a plain `curl` in cron.

Context budget

Two things are paid in tokens: tool definitions, loaded once per session, and tool

responses, paid on every call. Both were measured on a live seller account rather

than estimated — `scripts/collect_corpus.py` takes a snapshot of read-only tools

(PII masked before anything is written to disk, the corpus stays out of the repo),

`scripts/measure_corpus.py` reports what it costs.

Definitions. 151 tools cost 12 300 tokens with a single store configured,

down from 18 386: one-sentence descriptions, `shop_id` dropped from the schemas when

only one store exists, no empty schema fields.

Responses. The real problem turned out to be a handful of giant payloads:

What the server does about it:

• `view: compact | full`. Heavy tools return the fields they are called for;

`view="full"` gives the raw API response, and the answer states which fields were

hidden so the model knows what it can ask for.

• Truncation signal. When exactly `limit` records come back, the answer says the

data is partial — otherwise the model reasons about a slice and presents it as the

whole catalogue.

• Size guard. A response that would not fit the client's output ceiling

(`MAX_MCP_OUTPUT_TOKENS`, 25 000 by default in Claude Code) is cut server-side with

a count of what was left out, instead of being silently truncated on arrival.

• Search and depth for the category tree. The API has neither and returns all

9 797 nodes; `search` finds a category, `depth` controls the level, and the default

is the top level only.

Notes arrive as separate content blocks rather than a field inside the JSON: several

Ozon endpoints return an array at the top level, and wrapping it would break every

path into the data.

Tool profiles. A client without tool search pays for the whole catalogue on every

request. `OZON_TOOLSETS` keeps only the profiles you use, cut along working tasks

rather than documentation sections:

The `core` profile — stores, diagnostics, degradations, company — is always on:

diagnostics are needed exactly when something is broken. Disabled profiles are listed

in the `ozon_list_shops` description, and calling a disabled tool answers which profile

contains it, so the assistant names the reason instead of saying "this is not possible".

Claude Code needs none of this: it has tool search enabled by default. Cursor, Cline,

Continue and Claude Desktop fetch `tools/list` whole — profiles are for them.

Design decisions

• 151 narrow tools, not a few generic ones. Collapsing them into `action`-style

endpoints would save definition tokens and change the class of failure: instead of

"no such tool" you get a wrong call with a side effect, and some of these tools set

prices and start ad campaigns.

• The server diagnoses itself. `ozon_diagnostics` checks host availability and

runs a light real request across 12 Seller API categories plus the Performance API

keys; `ozon_degradations` reports which tools used to work and now fail steadily.

Ozon retires endpoints without notice, so "is it my keys or did the API move" has to

be answerable in one call.

• `compact` is the default for heavy tools. The corpus showed the hidden fields are

promo history, warehouse timetables and logistics internals — not the data decisions

are made from — and the response says what was hidden.

• Response shaping hangs on a contextvar. The dispatcher here is one long if-chain

with 150 `_json` calls; threading the tool name and arguments through every branch by

hand would be 150 edit sites and 150 chances to miss one.

• `shop_id` disappears from schemas with one store, and comes back the moment a

second one appears.

• `mcp<2` is pinned deliberately — the 2.0 low-level API drops the decorator

handlers this server is built on; the pin is documented where it is set.

• Keys are encrypted at rest (Fernet, key in the data volume) and masked in the UI;

the corpus collector masks personal data before writing a file.

How it works

A single Docker container running a FastAPI application that is both the MCP

server and the web UI.

• `ozon_mcp/server.py` — the MCP server itself. The `TOOLS` list describes all

151 tools (name, description, JSON schema for the arguments) and the `call_tool`

handler routes each call to the right Ozon client method. Clients are pooled per

`shop_id`, so switching stores reconnects nothing.

• `ozon_mcp/client.py` — two HTTP clients: `OzonSellerClient` (`Client-Id` /

`Api-Key` headers) and `OzonPerformanceClient` (a `client_credentials` token that

lives 30 minutes and refreshes itself).

• `ozon_mcp/app.py` — FastAPI: the `/sse` endpoint on top of

`SseServerTransport`, Bearer-token checking, the dashboard/stores/diagnostics

pages, and the background health-check task.

• `ozon_mcp/settings.py` — stores and keys: Fernet encryption, masking for the

UI, picking up keys from environment variables as a store called `default`, and

migrating the old single-store `settings.json` into `shops.json`.

• `ozon_mcp/diagnostics.py` — probes: pinging Ozon hosts plus lightweight real

requests across 12 Seller API categories, and a Performance API key check.

• `ozon_mcp/stats.py` — SQLite via `aiosqlite`: every tool call with its

duration and outcome, health-check history, degradation calculation.

The hosts the server talks to:

Non-obvious things:

• Ozon returns ad bids and budgets in micro-rubles: `1000000` = 1 ₽. Don't be

surprised by seven-digit numbers.

• A `403` on reviews and questions is not a breakage — it means no Premium Plus

subscription. Diagnostics does not count those as errors.

• Ozon API keys became time-limited after the 2026-02-13 rotation — 180 days. The

expiry is exposed explicitly: `POST /v1/roles` returns `expires_at`, so you can

warn ahead of time instead of catching a `401` in the probes.

• Asynchronous ad statistics: one report at a time, ≤10 campaigns, ≤62 days. The

tool waits up to about 2 minutes for the report to be ready.

• Supply-order statuses in API v3 are integers 1–8, not strings.

Environment variables

Known Ozon API limitations (as of August 2026)

• Advertising: the API can only create "Trafarety" CPC campaigns; budgets and bids

are in micro-rubles; there is no official way to read the ad account balance.

• "Pay per order": bids have been fixed since February 2025 — you can only turn

the promotion on or off.

• Reviews, questions and part of analytics require a Premium Plus subscription

(error code 7).

• Funnel metrics in `ozon_analytics` are marked deprecated by Ozon — use

`ozon_product_queries` for search positions.

• Endpoints Ozon is switching off in autumn 2026. Dates from the official

@OzonSellerAPI channel, verified against live seller accounts

(issue #6,

thanks to @standlord-prog):

`/v4/posting/fbs/list` is not a rename of v3: `postings` sit at the top level

rather than under `result`, and pagination is cursor-based (`has_next` + `cursor`)

instead of `offset`.

• `ozon_finance_cash_flow` and `ozon_finance_accruals` already run on the new paths

(`/v1/finance/cash-flow-statement/list`, `/v1/finance/accrual/by-day`).

• `ozon_product_stocks_by_warehouse` uses v2 because v1 is switched off on 2026-04-07.
• Digital FBS handover acts were removed by Ozon on 2026-03-22 — the regular act

is used instead.

• The Ozon API has no "edit a review reply" method: the reply is deleted and

written again.

This list is not a rewrite of the reference: it comes from the degradation log and

five months of daily calls, cross-checked against docs.ozon.ru as of August 2026.

What changed in version 2.0

A full revision against the June 2026 Ozon API, verified by running real requests

rather than reading docs: the unified returns list, cancellations v2, realization

v2, ship v4, supply-order v3, real pricing strategies and "I want a discount",

the seller's own promotions, the new advertising model (Trafarety CPC + "Pay per

order"), diagnostics with a degradation detector, and authentication on the MCP

endpoint.

Project layout

ozon-mcp-server/
├── docker-compose.yml   # port 8000, ozon_data volume
├── Dockerfile           # python:3.12-slim, uvicorn
├── DEPLOY.md            # deploying to a dedicated machine, moving data
├── docs/                # client connection guides + tool reference
└── ozon_mcp/
    ├── server.py        # MCP server: 151 tools, multi-store
    ├── client.py        # Seller API + Performance API
    ├── app.py           # FastAPI: SSE, web, auth, health loop
    ├── diagnostics.py   # category probes, degradation detector
    ├── settings.py      # stores and keys (Fernet)
    ├── stats.py         # call statistics and check history (SQLite)
    └── templates/       # dashboard, diagnostics, shops

Deploying to a dedicated machine and moving stores across:

DEPLOY.md (Russian).

The same server for Wildberries

**wb-mcp-server** is the same

tool for the other marketplace (Wildberries is the other large Russian

marketplace): same architecture, same web UI with dashboard and diagnostics, same

multi-store model via `shop_id`, same SSE transport, same ways of connecting

clients.

In practice that means two things:

• The second server takes no new learning. Once you have set up one, the other

starts the same way; only the port (8001 instead of 8000) and the tool set differ.

• You can run both on one machine. Different ports, data in separate Docker

volumes, no conflict. In your client they are simply two MCP servers: `ozon` at

`http://localhost:8000/sse` and `wb` at `http://localhost:8001/sse`.

Sharing one machine does not hurt on rate limits either: both go out from the same

IP, but Ozon and Wildberries count limits on their own side — they are different

marketplaces. The cap on the number of seller accounts described in the multi-store

section applies within each marketplace separately.

Updates and support

Ozon changes its API constantly: endpoints get added, renamed and switched off

(the limitations section above lists what has been caught so far). This server is

the author's working tool, and it gets updated when he needs it updated — that

is, when a change breaks something in his own stores. More than five months of

daily use, and commits appear when Ozon breaks something, not on a schedule: a gap

between commits usually means everything is working. The upside is that the code is

proven by real daily use rather than published and forgotten; the downside is that

there is no release schedule and no commitment on turnaround.

If you need a fix urgently, write to d0371153@gmail.com.

Issues and pull requests are welcome too, and they do get read.

Acknowledgements

• @standlord-prog:
  • issue #6 — the breakdown

of Ozon endpoints being switched off, verified against live seller accounts: dates,

replacements and three gotchas in the move to `/v4`. Separately — the warning that

`/v1/carriage/create` has no required fields and an empty `{}` body creates a real

shipment, and the correction about `POST /v1/roles` returning `expires_at`.

Version v2.1.0 is built on that work.

blind diagnostics: in stdio mode call statistics were never initialised, so

`ozon_degradations` answered "no degradations" to every question — even when every

single call was failing. The tool is marked [P0] and is asked precisely when something

has broken, which makes a silent false negative worse than having no tool at all. The

PR does not just fix the wiring: it also separates "no data" from "no degradations"

and adds an integration test over stdio with a real MCP client. Shipped in v2.1.2.

Version history: CHANGELOG.md.

License

MIT — see LICENSE.

MCP Registry

Published in the official MCP Registry:

mcp-name: io.github.DeviceIngineering/ozon-mcp-server