Ozon MCP Server

Ozon MCP Server

Run your Ozon stores straight from a chat with an AI assistant: prices, promos, advertising, orders, returns, reviews, finances — 156 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, 156 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](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