Ozon MCP Server

Ozon MCP Server

Gerencie suas lojas Ozon diretamente de um chat com um assistente de IA: preços, promoções, publicidade, pedidos, devoluções, avaliações, finanças — 156 ferramentas sobre a Ozon Seller API e a Performance API (a Ozon é o maior marketplace da Rússia; a Seller API cobre catálogo e operações, a Performance API cobre anúncios pagos). Feito para vendedores que operam mais de uma loja: cada chamada recebe um shop_id, e as chaves de API permanecem criptografadas no seu próprio servidor — nada sai dele. O que o diferencia de outros servidores MCP da Ozon: ele cobre publicidade além da Seller API, e seus diagnósticos integrados informam quais endpoints da Ozon quebraram antes que seu assistente esbarre neles.

Vende também no Wildberries? Existe o mesmo servidor para WB — wb-mcp-server.

Esta é a ferramenta de trabalho do próprio autor: mais de cinco meses de uso diário, cerca de vinte contas de vendedor, 156 ferramentas. Ela é atualizada quando ele precisa — veja Atualizações e suporte para saber o que isso significa para você.

Os guias de instalação por cliente em docs/ estão atualmente apenas em russo. A configuração neles é JSON pronto para colar, que se lê igual em qualquer idioma: caminhos de arquivo, a URL http://localhost:8000/sse e o cabeçalho Authorization: Bearer <MCP_AUTH_TOKEN>.

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.

O que ele faz

Grupo	Ferramentas	O que contém
Promoções e descontos	14	Promoções da Ozon (lista, candidatos, entrar/sair), promoções próprias do vendedor, solicitações de compradores "quero desconto"
Preços e estratégias de precificação	14	definição de preços e preço mínimo, índice de preços, temporizador de preço mínimo, estratégias automáticas que acompanham concorrentes
Publicidade (Performance API)	22	campanhas CPC "Trafarety" (formato de colocação patrocinada da Ozon), lances e orçamentos, "Pague por pedido" (CPO), estatísticas por produto e diárias
Produtos	21	listagens e cartões, atributos, estoque, importação e atualizações em massa, mídia, arquivo, certificados
Pedidos FBS e FBO	17	pedidos não atendidos, embalagem (v4), etiquetas, cancelamentos, atos de entrega, país de origem
Devoluções e cancelamentos	10	lista unificada de devoluções FBO+FBS, reclamações rFBS que exigem decisão do vendedor, solicitações de cancelamento
Avaliações, perguntas, chats	13	avaliações e respostas, perguntas de compradores, conversas de chat (v3)
Armazéns e relatórios	8	armazéns FBS, métodos de entrega, geração e download de relatórios
Finanças	7	saldo, transações, acréscimos, relatório de realização, acordos mútuos, fluxo de caixa
Categorias, marcas, certificados	7	árvore de categorias, atributos e seus valores permitidos, certificados
Análises	5	análises de SKU, estoque e rotatividade, posições de produtos na busca da Ozon, principais consultas de busca
Suprimentos FBO	4	ordens de suprimento (v3), contadores, janelas de horário
Avaliação	2	avaliação atual do vendedor e seu histórico
Diagnósticos	2	autoverificação da disponibilidade da API da Ozon, detector de degradação
Notificações	2	assinaturas de webhook push e a referência de tipos de evento
Empresa	2	dados do vendedor e tarifas
Lojas	1	lista de lojas conectadas e seus shop_id

FBO e FBS são os modelos de fulfillment da Ozon: FBO envia dos armazéns da Ozon, FBS dos seus, rFBS é FBS com entrega própria.

A lista numerada completa, com descrição e parâmetros de cada ferramenta, está em docs/tools.md. Ela é gerada a partir de ozon_mcp/server.py (a constante TOOLS) — a mesma coisa que tools/list retorna para qualquer cliente MCP.

Início rápido

Opção 1: um comando, sem Docker

O servidor fala stdio, que é como Claude Desktop, Cursor, VS Code e outros clientes MCP se conectam a ele. Nada para compilar:

uvx ozon-mcp-server

Ou via pip:

pip install ozon-mcp-server
ozon-mcp

Configuração do cliente (por exemplo, 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"
      }
    }
  }
}

Aponte DATA_DIR para qualquer diretório gravável — ele guarda lojas, chaves e estatísticas. O padrão é /data, que é o caminho usado dentro do Docker.

Opção 2: Docker com o painel web

Use esta opção se quiser o painel, diagnósticos da API da Ozon e gerenciamento de lojas baseado em navegador. Cinco comandos:

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

O que cada etapa faz:

• .env — toda variável é opcional. As chaves das lojas são mais fáceis de inserir na interface web do que aqui. A única coisa que vale configurar de antemão, se o servidor for acessível por qualquer pessoa além de você, é MCP_AUTH_TOKEN (gere uma com openssl rand -hex 32).
• docker compose up -d --build — cria a imagem a partir do Dockerfile, mapeia a porta 8000:8000 e cria o volume ozon_data para lojas, chaves, estatísticas de chamadas e histórico de diagnósticos. restart: unless-stopped traz o contêiner de volta após uma reinicialização.
• /shops — o formulário de adicionar loja: shop_id (o identificador que você usará no chat), um nome de exibição, Client-Id + Api-Key para a Seller API, e Client-Id + Client-Secret para a Performance API. O botão "Проверить" (Testar) faz uma solicitação ao vivo para a Ozon e informa se as chaves foram aceitas.

Depois que estiver em execução:

Endereço	O que é
http://localhost:8000/	painel: contadores de chamadas, erros, degradações
http://localhost:8000/shops	lojas e chaves
http://localhost:8000/diagnostics	diagnósticos da API da Ozon
http://localhost:8000/api/health	endpoint de saúde, JSON
http://localhost:8000/sse	o endpoint MCP — é para onde os clientes apontam

Observe que a interface web está em russo.

Para parar: docker compose down (os dados permanecem no volume ozon_data). Logs: docker compose logs -f.

Sem Docker

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

DATA_DIR tem como padrão /data, então ao executar localmente certifique-se de apontá-lo para um diretório no qual você possa gravar.

Instalação em clientes

O transporte é SSE em http://<host>:8000/sse. O suporte a SSE difere entre clientes: alguns falam diretamente, outros precisam da ponte mcp-remote. Há um guia por cliente, com caminhos de configuração para macOS, Linux e Windows e JSON pronto — em russo, mas os blocos JSON são neutros em idioma:

Cliente	SSE diretamente	Guia
Claude Code	sim	docs/install-claude-code.md
Claude Desktop	não, ponte mcp-remote	docs/install-claude-desktop.md
Cursor	sim	docs/install-cursor.md
Windsurf / Devin Desktop	sim	docs/install-windsurf.md
VS Code (GitHub Copilot)	sim	docs/install-vscode-copilot.md
Cline	sim	docs/install-cline.md
Continue.dev	sim	docs/install-continue.md
Zed	não confirmado, ponte recomendada	docs/install-zed.md
JetBrains AI Assistant / Junie	sim	docs/install-jetbrains.md
Gemini CLI	sim	docs/install-gemini-cli.md
OpenAI Codex CLI	não, ponte mcp-remote	docs/install-codex.md

O exemplo mais curto, Claude Code:

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

Resumo do cliente e referência da ponte: docs/README.md.

Multi-loja e segurança

As lojas são adicionadas na interface web, e toda ferramenta recebe um shop_id obrigatório; ozon_list_shops informa quais existem. No chat, fica assim: "mostre o estoque na loja alpha".

O ganho real não é a troca em si, mas que uma estratégia é escrita uma vez e implantada em todas as contas: uma regra sobre preços, respostas a avaliações ou lances de anúncios se aplica a todas as lojas de uma vez — sem entrar e sair de contas de vendedor, sem copiar chaves entre configurações de clientes.

O preço que você paga é um IP compartilhado. Cada conta fala com a Ozon a partir de um endereço: o servidor onde o MCP roda. Os limites de taxa da Ozon são contados por endereço, entre outras coisas, então quanto mais contas você tiver e quanto mais suas estratégias as usarem, mais próximo o tráfego combinado fica do limite onde a limitação ou um bloqueio entra em ação.

• não há limite no número de lojas no código;
• o teto real vem dos limites por IP da Ozon, não deste servidor;
• cerca de vinte contas é a estimativa do próprio autor de onde o tráfego ainda permanece na zona segura;
• além disso, distribua as lojas entre vários servidores com endereços diferentes.

Você pode ver o limite se aproximando, e o lugar para ver é a interface web: pings falhos e avisos de diagnóstico começam a se acumular, e a parcela de erros nas estatísticas de chamadas dispara. O painel também distingue os dois casos — limitação em massa parece muitas ferramentas degradando ao mesmo tempo, um endpoint quebrado parece uma única.

Como as chaves são armazenadas:

• no primeiro uso, .encryption_key — uma chave Fernet — é criada em DATA_DIR;
• as chaves das lojas são criptografadas com ela e mantidas em DATA_DIR/shops.json;
• a interface web mostra as chaves mascaradas (abc***xyz), e salvar um valor mascarado não sobrescreve o real;
• sob Docker, tudo isso vive no volume ozon_data. Para mover para outra máquina, copie o volume inteiro — caso contrário, você perde a chave de criptografia (veja DEPLOY.md, em russo).

O que saber sobre acesso:

• MCP_AUTH_TOKEN protege apenas /sse. Passe-o como o cabeçalho Authorization: Bearer … ou como um parâmetro de consulta ?token=….
• Um MCP_AUTH_TOKEN vazio significa nenhuma autenticação. Só é aceitável em uma rede confiável.
• A interface web (/, /shops, /diagnostics) e /api/* não estão atrás do token: qualquer pessoa que alcance a porta vê o painel e pode adicionar lojas.
• Não exponha a porta 8000 diretamente à internet. Para acesso remoto, use Tailscale ou uma VPN.
• O servidor não encerra HTTPS. Se precisar de TLS de fora, coloque um proxy reverso na frente.

A interface web: toda chamada é visível

Com um servidor MCP típico, as chamadas desaparecem no vazio: o assistente fez algo, mas o quê exatamente, quanto tempo levou e qual erro encontrou só é conhecido pelo assistente. Aqui, toda chamada ganha uma linha no log, e toda ferramenta quebrada ganha um marcador no painel. Para uma ferramenta que move dinheiro real em uma loja, isso não é decoração — é a condição para confiar nela.

As estatísticas de chamadas e o histórico de verificações não são sintéticos: vêm de mais de cinco meses de uso diário em cerca de vinte contas de vendedor. A lista de mudanças capturadas na API da Ozon na seção de limitações vem do mesmo lugar — foi lida do log de degradação, não copiada da documentação.

Painel /

A captura de tela está no topo desta página.

• Quatro contadores no topo: total de chamadas, chamadas hoje, erros e duração média de chamada em milissegundos.
• Top 10 ferramentas: contagem de chamadas, duração média e quantas dessas chamadas falharam.
• Um feed das últimas 50 chamadas: timestamp, shop_id, nome da ferramenta, duração, sucesso ou falha e o texto do erro.
• Um filtro por loja (/?shop=alpha) — os mesmos números para uma única conta.
• Dois banners aparecem no topo: ferramentas degradadas e "a última verificação da API da Ozon encontrou problemas".

Lojas /shops

As contas são adicionadas e removidas direto no navegador, sem edição de arquivos e sem reiniciar o contêiner. O botão "Проверить" (Testar) faz uma solicitação ao vivo para ambas as APIs (POST /api/shops/{shop_id}/test), então as chaves são verificadas quando você as adiciona, em vez de durante a primeira chamada real no meio de uma tarefa. Os tokens são criptografados com Fernet, a chave de criptografia vive em DATA_DIR/.encryption_key, e a interface mostra as chaves mascaradas.

Diagnósticos /diagnostics

(a captura de tela mostra uma loja de demonstração com chaves deliberadamente inválidas, por isso cada teste está vermelho)

• Por loja: se as chaves estão definidas, disponibilidade do host Ozon, 12 sondas da categoria Seller API e uma verificação de chave da Performance API.
• Uma verificação em segundo plano a cada HEALTH_CHECK_INTERVAL_MIN minutos (30 por padrão, 0 a desativa), além de um botão "Проверить сейчас" (Verificar agora) para execução imediata (POST /api/diagnostics/run).
• Histórico de verificações: hora, loja, status, número de pings com falha, número de sondas com falha e os textos de aviso. A interface mostra as últimas 30 entradas; até 1000 são mantidas no banco de dados com rotação automática.
• Os mesmos dados estão disponíveis no chat por meio da ferramenta ozon_diagnostics.

Detector de degradação

O servidor percebe sozinho que a Ozon quebrou ou desativou um endpoint — não pela documentação nem por trabalho que falhou, mas pelas próprias estatísticas. Uma ferramenta cujas últimas três chamadas consecutivas falharam enquanto chamadas anteriores tiveram sucesso entra na lista de degradação, que mostra o nome da ferramenta, a hora da última chamada bem-sucedida, o número de erros consecutivos e o texto do erro mais recente. No painel, isso é um banner vermelho; na página de diagnósticos, uma tabela.

O que isso traz para você: uma mudança no lado da Ozon fica visível no dia em que acontece, não uma semana depois quando você descobre que os preços não estão sendo atualizados. A mesma lista está disponível no chat via ozon_degradations.

JSON para monitoramento externo

Tudo o que foi mencionado acima pode ser coletado programaticamente, não apenas visualizado:

Endpoint	O que retorna
GET /api/health	status do serviço, se a autenticação está ativada, verificações recentes, ferramentas degradadas
GET /api/stats	o mesmo resumo do painel; ?shop= restringe a uma loja
GET /api/diagnostics/{shop_id}	uma execução completa de diagnóstico ao vivo para uma loja

Isso é suficiente para integrar o servidor ao Zabbix, Uptime Kuma ou um simples curl no cron.

Orçamento de contexto

Duas coisas são pagas em tokens: definições de ferramentas, carregadas uma vez por sessão, e respostas de ferramentas, pagas a cada chamada. Ambas foram medidas em uma conta de vendedor real, em vez de estimadas — scripts/collect_corpus.py tira um instantâneo das ferramentas somente leitura (PII mascarada antes que qualquer coisa seja gravada em disco, o corpus permanece fora do repositório), scripts/measure_corpus.py relata o custo.

Definições. 156 ferramentas custam 12 300 tokens com uma única loja configurada, abaixo de 18 386: descrições de uma frase, shop_id removido dos esquemas quando existe apenas uma loja, sem campos de esquema vazios.

Respostas. O problema real acabou sendo um punhado de payloads gigantes:

ferramenta	antes	depois
ozon_category_tree — uma árvore de 9 797 nós	266 324	979
ozon_get_prices — 93 % do peso é histórico de promoções	52 879	8 679
ozon_returns_fbo — 50 devoluções com logística completa	24 277	8 458
ozon_warehouse_list — 99 % do peso é um ano de cronogramas	20 132	370
corpus de 16 respostas ao vivo	476 158	63 845

O que o servidor faz a respeito:

• view: compact | full. Ferramentas pesadas retornam os campos para os quais foram chamadas; view="full" fornece a resposta bruta da API, e a resposta indica quais campos foram ocultados para que o modelo saiba o que pode solicitar.
• Sinal de truncamento. Quando exatamente limit registros retornam, a resposta diz que os dados são parciais — caso contrário, o modelo raciocina sobre uma fatia e a apresenta como o catálogo inteiro.
• Proteção de tamanho. Uma resposta que não caberia no limite de saída do cliente (MAX_MCP_OUTPUT_TOKENS, 25 000 por padrão no Claude Code) é cortada no lado do servidor com uma contagem do que foi omitido, em vez de ser silenciosamente truncada na chegada.
• Busca e profundidade para a árvore de categorias. A API não tem nenhuma das duas e retorna todos os 9 797 nós; search encontra uma categoria, depth controla o nível, e o padrão é apenas o nível superior.

As notas chegam como blocos de conteúdo separados, em vez de um campo dentro do JSON: vários endpoints da Ozon retornam um array no nível superior, e envolvê-lo quebraria todos os caminhos até os dados.

Perfis de ferramentas. Um cliente sem busca de ferramentas paga pelo catálogo inteiro em cada solicitação. OZON_TOOLSETS mantém apenas os perfis que você usa, cortados ao longo de tarefas de trabalho em vez de seções de documentação:

OZON_TOOLSETS	ferramentas	tokens
vazio (padrão)	151	12 686
pricing,ads	57	5 425
orders	33	2 611

O perfil core — lojas, diagnósticos, degradações, empresa — está sempre ativo: diagnósticos são necessários exatamente quando algo está quebrado. Perfis desativados são listados na descrição de ozon_list_shops, e chamar uma ferramenta desativada responde qual perfil a contém, para que o assistente indique o motivo em vez de dizer "isso não é possível".

O Claude Code não precisa de nada disso: ele tem busca de ferramentas ativada por padrão. Cursor, Cline, Continue e Claude Desktop buscam tools/list inteiro — os perfis são para eles.

Decisões de design

• 151 ferramentas estreitas, não algumas genéricas. Colapsá-las em endpoints estilo action economizaria tokens de definição e mudaria a classe de falha: em vez de "ferramenta inexistente", você obtém uma chamada errada com efeito colateral, e algumas dessas ferramentas definem preços e iniciam campanhas de anúncios.
• O servidor diagnostica a si mesmo. ozon_diagnostics verifica a disponibilidade do host e executa uma solicitação real leve em 12 categorias da Seller API além das chaves da Performance API; ozon_degradations relata quais ferramentas funcionavam e agora falham de forma constante. A Ozon aposenta endpoints sem aviso, então "são minhas chaves ou a API mudou" precisa ser respondível em uma única chamada.
• compact é o padrão para ferramentas pesadas. O corpus mostrou que os campos ocultos são histórico de promoções, cronogramas de armazém e internals de logística — não os dados a partir dos quais decisões são tomadas — e a resposta informa o que foi ocultado.
• A modelagem de resposta depende de uma contextvar. O despachante aqui é uma longa cadeia if com 150 chamadas _json; passar o nome da ferramenta e argumentos por cada ramo manualmente seriam 150 pontos de edição e 150 chances de errar um.
• shop_id desaparece dos esquemas com uma loja, e volta no momento em que uma segunda aparece.
• mcp<2 é fixado deliberadamente — a API de baixo nível 2.0 remove os manipuladores de decorador nos quais este servidor é construído; a fixação é documentada onde é definida.
• As chaves são criptografadas em repouso (Fernet, chave no volume de dados) e mascaradas na interface; o coletor de corpus mascara dados pessoais antes de gravar um arquivo.

Como funciona

Um único contêiner Docker executando um aplicativo FastAPI que é tanto o servidor MCP quanto a interface web.

• ozon_mcp/server.py — o próprio servidor MCP. A lista TOOLS descreve todas as 156 ferramentas (nome, descrição, esquema JSON para os argumentos) e o manipulador call_tool roteia cada chamada para o método correto do cliente Ozon. Os clientes são agrupados por shop_id, então alternar lojas não reconecta nada.
• ozon_mcp/client.py — dois clientes HTTP: OzonSellerClient (cabeçalhos Client-Id / Api-Key) e OzonPerformanceClient (um token client_credentials que dura 30 minutos e se renova sozinho).
• ozon_mcp/app.py — FastAPI: o endpoint /sse sobre SseServerTransport, verificação de Bearer-token, as páginas de painel/lojas/diagnósticos e a tarefa de verificação de saúde em segundo plano.
• ozon_mcp/settings.py — lojas e chaves: criptografia Fernet, mascaramento para a interface, captação de chaves de variáveis de ambiente como uma loja chamada default, e migração do antigo settings.json de loja única para shops.json.
• ozon_mcp/diagnostics.py — sondas: ping em hosts Ozon além de solicitações reais leves em 12 categorias da Seller API, e uma verificação de chave da Performance API.
• ozon_mcp/stats.py — SQLite via aiosqlite: cada chamada de ferramenta com sua duração e resultado, histórico de verificação de saúde, cálculo de degradação.

Os hosts com os quais o servidor fala:

API	URL base	Autorização
Seller API	api-seller.ozon.ru	cabeçalhos Client-Id e Api-Key
Performance API (anúncios)	api-performance.ozon.ru	OAuth client_credentials, token de 30 minutos

Coisas não óbvias:

• A Ozon retorna lances e orçamentos de anúncios em microrrublos: 1000000 = 1 ₽. Não se surpreenda com números de sete dígitos.
• Um 403 em avaliações e perguntas não é uma falha — significa que não há assinatura Premium Plus. Os diagnósticos não contam isso como erros.
• As chaves da API Ozon tornaram-se limitadas no tempo após a rotação de 2026-02-13 — 180 dias. A expiração é exposta explicitamente: POST /v1/roles retorna expires_at, para que você possa avisar com antecedência em vez de pegar um 401 nas sondas.
• Estatísticas de anúncios assíncronas: um relatório por vez, ≤10 campanhas, ≤62 dias. A ferramenta espera até cerca de 2 minutos para o relatório ficar pronto.
• Status de pedidos de fornecimento na API v3 são inteiros 1–8, não strings.

Variáveis de ambiente

Variável	Padrão	Propósito
MCP_AUTH_TOKEN	vazio	Token Bearer para /sse. Vazio = sem autenticação
HEALTH_CHECK_INTERVAL_MIN	30	intervalo de diagnósticos em segundo plano, 0 o desativa
PORT	8000	porta do servidor HTTP
OZON_TOOLSETS	vazio	perfis de ferramentas separados por vírgula: pricing, ads, catalog, orders, analytics, feedback, finance; vazio significa todas as 156
OZON_MAX_RESPONSE_CHARS	60000	limite da proteção de tamanho para uma única resposta
DATA_DIR	/data	diretório que contém shops.json, stats.db, .encryption_key
OZON_CLIENT_ID, OZON_API_KEY	vazio	chaves da Seller API para a loja default, se você preferir não usar a interface
OZON_PERF_CLIENT_ID, OZON_PERF_CLIENT_SECRET	vazio	o mesmo para a Performance API

Limitações conhecidas da API Ozon (em agosto de 2026)

• Publicidade: a API só pode criar campanhas CPC "Trafarety"; orçamentos e lances estão em microrrublos; não há uma forma oficial de ler o saldo da conta de anúncios.

• "Pague por pedido": os lances estão fixos desde fevereiro de 2025 — você só pode ativar ou desativar a promoção.

• Avaliações, perguntas e parte da análise exigem uma assinatura Premium Plus (código de erro 7).

• Métricas de funil em ozon_analytics estão marcadas como obsoletas pela Ozon — use ozon_product_queries para posições de busca.

• Endpoints que a Ozon está desativando no outono de 2026. Datas do canal oficial @OzonSellerAPI, verificadas em contas de vendedor reais (issue #6, agradecimentos a @standlord-prog):

  caminho	fica offline	substituição
  /v3/posting/fbs/list	2026-08-31	/v4/posting/fbs/list — feito na v2.1.0
  /v2/posting/fbo/list	2026-08-31	/v3/posting/fbo/list — feito na v2.1.0
  /v3/posting/fbs/unfulfilled/list	2026-08-31	sem substituição: filtrado de /v4/posting/fbs/list por status — feito na v2.1.0
  /v2/posting/fbs/act/create	2026-09-07	/v1/carriage/create + /v1/carriage/approve — em andamento
  /v3/finance/transaction/list	2026-09-08	/v1/finance/accrual/by-day — em andamento
  /v3/finance/transaction/totals	2026-09-08	o mesmo — em andamento

  /v4/posting/fbs/list não é uma renomeação da v3: postings ficam no nível superior em vez de sob result, e a paginação é baseada em cursor (has_next + cursor) em vez de offset.

• ozon_finance_cash_flow e ozon_finance_accruals já rodam nos novos caminhos (/v1/finance/cash-flow-statement/list, /v1/finance/accrual/by-day).

• ozon_product_stocks_by_warehouse usa v2 porque a v1 é desativada em 2026-04-07.

• Os atos de entrega digital FBS foram removidos pela Ozon em 2026-03-22 — o ato regular é usado em seu lugar.

• A API Ozon não tem um método "editar resposta a avaliação": a resposta é excluída e escrita novamente. Esta lista não é uma reescrita da referência: ela vem do log de degradação e de cinco meses de chamadas diárias, verificadas cruzadamente com docs.ozon.ru em agosto de 2026.

O que mudou na versão 2.0

Uma revisão completa contra a API da Ozon de junho de 2026, verificada executando requisições reais em vez de ler a documentação: a lista unificada de devoluções, cancelamentos v2, realização v2, ship v4, supply-order v3, estratégias de preço reais e "quero desconto", as promoções do próprio vendedor, o novo modelo de publicidade (Trafarety CPC + "Pague por pedido"), diagnósticos com detector de degradação e autenticação no endpoint MCP.

Estrutura do projeto

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: 156 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

Implantação em uma máquina dedicada e migração de lojas: DEPLOY.md (em russo).

O mesmo servidor para Wildberries

wb-mcp-server é a mesma ferramenta para o outro marketplace (Wildberries é o outro grande marketplace russo): mesma arquitetura, mesma interface web com painel e diagnósticos, mesmo modelo multi-loja via shop_id, mesmo transporte SSE, mesmas formas de conectar clientes.

	Ozon MCP Server	WB MCP Server
Porta	8000	8001
Ferramentas	151	202
API	Ozon Seller API + Performance API (anúncios)	Wildberries Seller API

Na prática, isso significa duas coisas:

• O segundo servidor não exige novo aprendizado. Depois de configurar um, o outro inicia da mesma forma; apenas a porta (8001 em vez de 8000) e o conjunto de ferramentas diferem.
• Você pode executar ambos em uma única máquina. Portas diferentes, dados em volumes Docker separados, sem conflito. No seu cliente, eles são simplesmente dois servidores MCP: ozon em http://localhost:8000/sse e wb em http://localhost:8001/sse.

Compartilhar uma máquina também não prejudica os limites de taxa: ambos saem do mesmo IP, mas Ozon e Wildberries contam os limites do próprio lado — são marketplaces diferentes. O limite no número de contas de vendedor descrito na seção de multi-loja se aplica separadamente dentro de cada marketplace.

Do acesso à API a um reprecificador funcional

Este servidor dá a um modelo acesso à conta do vendedor. Decidir qual deve ser o preço é uma tarefa separada, e o ozon-wildberries-repricer faz isso: ele mantém um preço de referência, calcula um piso de ponto de equilíbrio a partir das taxas reais de cada marketplace, retira produtos de promoções que os colocariam abaixo do custo e pode buscar um preço melhor executando um experimento controlado em vendas ao vivo.

Ele cobre Ozon, Wildberries e Yandex Market em um só lugar, e tem seu próprio plano de controle HTTP para agentes de LLM — com as proteções que um modelo precisa: uma mudança de preço que acionaria a quarentena do Wildberries é percorrida em várias execuções, os preços são relidos três minutos depois porque os marketplaces relatam sucesso para alterações que não fizeram, e vários agentes trabalhando no mesmo catálogo não podem sobrescrever as decisões uns dos outros.

Execute sem uma conta de marketplace: npm run demo gera um catálogo sintético e inicia o aplicativo.

Atualizações e suporte

A Ozon muda sua API constantemente: endpoints são adicionados, renomeados e desativados (a seção de limitações acima lista o que foi capturado até agora). Este servidor é a ferramenta de trabalho do autor e é atualizado quando ele precisa — ou seja, quando uma mudança quebra algo em suas próprias lojas. Mais de cinco meses de uso diário, e os commits aparecem quando a Ozon quebra algo, não em um cronograma: uma lacuna entre commits geralmente significa que tudo está funcionando. O lado positivo é que o código é comprovado pelo uso diário real, em vez de publicado e esquecido; o lado negativo é que não há cronograma de lançamento nem compromisso de prazo.

Se você precisar de uma correção urgente, escreva para d0371153@gmail.com. Issues e pull requests também são bem-vindos, e eles são lidos.

Agradecimentos

• @standlord-prog:
  • issue #6 — o detalhamento dos endpoints da Ozon que foram desativados, verificado contra contas de vendedor ao vivo: datas, substituições e três pegadinhas na migração para /v4. Separadamente — o aviso de que /v1/carriage/create não tem campos obrigatórios e um corpo {} vazio cria um envio real, e a correção sobre POST /v1/roles retornando expires_at. A versão v2.1.0 é construída sobre esse trabalho.
  • PR #7 — encontrou e corrigiu diagnósticos cegos: no modo stdio, as estatísticas de chamadas nunca eram inicializadas, então ozon_degradations respondia "sem degradações" a todas as perguntas — mesmo quando cada chamada individual estava falhando. A ferramenta é marcada como [P0] e é consultada precisamente quando algo quebrou, o que torna um falso negativo silencioso pior do que não ter ferramenta alguma. O PR não apenas corrige a conexão: ele também separa "sem dados" de "sem degradações" e adiciona um teste de integração via stdio com um cliente MCP real. Lançado na v2.1.2.

Histórico de versões: CHANGELOG.md.

Licença

MIT — veja LICENSE.

MCP Registry

Publicado no MCP Registry oficial:

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