Ozon MCP Server

Ozon MCP Server

Gerencie lojas Ozon diretamente do chat com o assistente de IA: preços, promoções, publicidade, pedidos, devoluções, avaliações, finanças — 151 ferramenta sobre a Ozon Seller API e Performance API. Para vendedores com várias lojas: cada chamada aceita shop_id, as chaves ficam armazenadas criptografadas no seu servidor, nada vaza para fora. Diferença em relação a outros Ozon-MCP: não cobre apenas a Seller API, mas também publicidade, e a diagnose integrada mostra quais métodos da Ozon quebraram, antes que o assistente perceba.

Vende também na Wildberries? Existe um servidor igual para WB — wb-mcp-server.

Esta é uma ferramenta de trabalho pessoal do autor: mais de cinco meses de uso diário, cerca de vinte painéis, 151 ferramentas. Ela é atualizada conforme a necessidade do próprio autor — detalhes na seção “Atualizações e suporte”.

Ты: Какие мои товары Ozon планирует затянуть в акцию?
Ты: Покажи расход по рекламным кампаниям за неделю и останови те, что тратят впустую.
Ты: У каких товаров индекс цены хуже, чем у конкурентов?
Ты: Ответь благодарностью на все новые отзывы с оценкой 5.

O que faz

Grupo	Ferramentas	O que contém
Promoções e descontos	14	promoções Ozon (lista, candidatos, entrada/saída), promoções próprias do vendedor, solicitações “Quero desconto”
Preços e estratégias de preço	14	definição de preços e preço mínimo, índice de preços, timer de preço mínimo, autoestratégias por concorrentes
Publicidade (Performance API)	22	campanhas “Estênceis” (CPC), lances e orçamentos, “Pagamento por pedido” (CPO), estatísticas por produtos e dias
Produtos	21	lista e fichas, atributos, estoques, importação e atualização em massa, mídia, arquivo, certificados
Pedidos FBS e FBO	17	pedidos não separados, separação (v4), etiquetas, cancelamentos, atos de recebimento, país do produto
Devoluções e cancelamentos	10	lista unificada de devoluções FBO+FBS, solicitações rFBS com decisão do vendedor, solicitações de cancelamento
Avaliações, perguntas, chats	13	avaliações e respostas, perguntas de compradores, conversas em chats (v3)
Armazéns e relatórios	8	armazéns FBS, métodos de entrega, geração e exportação de relatórios
Finanças	7	saldo, transações, acréscimos, realização, acertos, fluxo de caixa
Categorias, marcas, certificados	7	árvore de categorias, atributos e seus valores, certificados
Análise	5	análise por SKU, estoques e giro, posições de produtos na busca, top de consultas de busca
Fornecimentos FBO	4	solicitações de fornecimento (v3), contadores, time slots
Avaliação	2	avaliação atual do vendedor e seu histórico
Diagnóstico	2	autoverificação de disponibilidade da API Ozon, detector de degradações
Notificações	2	assinaturas de push webhooks e catálogo de tipos de eventos
Empresa	2	dados do vendedor e tarifas
Lojas	1	lista de lojas conectadas e seus shop_id

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

Início rápido

Opção 1: um comando, sem Docker

O servidor funciona via stdio — assim ele é conectado ao Claude Desktop, Cursor, VS Code e outros clientes MCP. Nada precisa ser compilado:

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": "ваш Client-Id",
        "OZON_API_KEY": "ваш API-ключ",
        "DATA_DIR": "~/.ozon-mcp"
      }
    }
  }
}

DATA_DIR aponte para qualquer diretório gravável — lá ficam armazenados lojas, chaves e estatísticas. Por padrão, usa-se /data (caminho para Docker).

Opção 2: Docker com interface web

Necessário se você quiser dashboard, diagnóstico da API Ozon e adição fácil de lojas pelo navegador. Cinco comandos:

git clone https://github.com/DeviceIngineering/ozon-mcp-server.git
cd ozon-mcp-server
cp .env.example .env               # для локальной сети можно оставить как есть
docker compose up -d --build       # соберёт образ и поднимет сервер на порту 8000
open http://localhost:8000/shops   # добавить магазин и ключи Ozon

O que cada passo faz:

• .env — todas as variáveis são opcionais. As chaves das lojas são mais fáceis de inserir na interface web do que aqui. A única coisa que vale definir de imediato, se o servidor for visível para outros além de você, é MCP_AUTH_TOKEN (gerar: openssl rand -hex 32).
• docker compose up -d --build — compila a imagem a partir de Dockerfile, encaminha a porta 8000:8000 e cria o volume ozon_data para lojas, chaves, estatísticas e histórico de diagnóstico. restart: unless-stopped iniciará o contêiner após reiniciar a máquina.
• /shops — formulário de adição de loja: shop_id (em latim, será assim que você operará no chat), nome, Client-Id + Api-Key da Seller API e Client-Id + Client-Secret da Performance API. O botão “Verificar” faz uma requisição real à Ozon e informa se as chaves foram aceitas.

Após a execução:

Endereço	O que é
http://localhost:8000/	dashboard: contadores de chamadas, erros, degradações
http://localhost:8000/shops	lojas e chaves
http://localhost:8000/diagnostics	diagnóstico da API Ozon
http://localhost:8000/api/health	endpoint de health, JSON
http://localhost:8000/sse	endpoint MCP, é ele que os clientes usam

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 por padrão /data — em execução local, é obrigatório redefinir para um diretório acessível.

Instalação nos clientes

Transporte — SSE, endereço http://<host>:8000/sse. O suporte a SSE varia entre clientes: alguns o entendem diretamente, outros precisam de uma ponte mcp-remote. Arquivo de instruções para cada cliente, com caminhos de configuração para macOS, Linux, Windows e JSON pronto:

Cliente	SSE direto	Instrução
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, recomendamos ponte	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 dos clientes e referência da ponte — docs/README.md.

Multi-loja e segurança

Os painéis são adicionados na interface web; cada ferramenta aceita o parâmetro obrigatório shop_id; para saber os disponíveis, use a ferramenta ozon_list_shops. No chat, isso fica assim: “mostre os estoques na loja alpha”.

O principal benefício não está na troca em si, mas no fato de que a estratégia é escrita uma vez e aplicada a todos os painéis: a regra de preços, de respostas a avaliações ou de lances se aplica a todas as lojas de uma vez — sem reautenticar nos painéis e sem copiar chaves entre configurações de clientes diferentes.

O custo dessa abordagem é o IP compartilhado. Todos os painéis acessam a Ozon a partir de um único endereço: o do servidor onde o MCP está instalado. Os limites da Ozon são calculados também por endereço, e quanto mais painéis e quanto mais ativas as estratégias neles, mais próximo o fluxo total fica do limite, a partir do qual começa o throttling ou bloqueio.

• não há limite de número de lojas no código;
• o teto real não é definido pelo servidor, mas pelos limites da Ozon por IP;
• cerca de vinte painéis — estimativa do autor, na qual o fluxo permanece na zona segura;
• além disso — distribuir as lojas entre vários servidores com endereços diferentes.

A aproximação do limite é visível com antecedência, justamente na interface web: cresce o número de pings com falha e de avisos no diagnóstico; na estatística de chamadas, a proporção de erros dispara. Dá para distinguir um do outro também pelo dashboard: throttling em massa parece uma degradação simultânea de muitas ferramentas; quebra de endpoint — degradação de uma só.

Como as chaves são armazenadas:

• no primeiro acesso em DATA_DIR, é criado .encryption_key — chave Fernet;
• as chaves das lojas são criptografadas com ela e ficam em DATA_DIR/shops.json;
• na interface web, as chaves aparecem mascaradas (abc***xyz); ao salvar, o valor mascarado não sobrescreve o real;
• no Docker, tudo isso fica no volume ozon_data; migrar para outra máquina — copiar o volume inteiro, caso contrário a chave de criptografia se perde (veja DEPLOY.md).

O que é importante saber sobre o acesso:

• MCP_AUTH_TOKEN protege apenas /sse. O token é enviado pelo cabeçalho Authorization: Bearer … ou pelo parâmetro ?token=….
• MCP_AUTH_TOKEN vazio = autorização desativada. Isso só é permitido em rede confiável.
• A interface web (/, /shops, /diagnostics) e /api/* não são protegidas por token: quem tiver acesso de rede à porta vê o dashboard e pode adicionar lojas.
• Não encaminhe a porta 8000 diretamente para a internet. Para acesso externo — Tailscale ou VPN.
• O servidor não termina HTTPS. Se precisar de acesso externo via TLS — use um reverse proxy.

Interface web: cada chamada visível

Em um servidor MCP comum, as chamadas vão para lugar nenhum: o assistente fez algo, mas o que exatamente, em quanto tempo e com qual erro — só ele sabe. Aqui, cada chamada tem uma linha no log, e cada ferramenta que quebrou — uma marca no dashboard. Para uma ferramenta que gerencia dinheiro real na loja, isso não é enfeite, é condição de confiança.

As estatísticas de chamadas e o histórico de verificações não são sintéticos: mais de cinco meses de uso diário em cerca de vinte painéis. Daí também vem a lista de mudanças capturadas na API Ozon na seção sobre limitações — ela não foi tirada da documentação, mas do log de degradações.

Dashboard /

Captura de tela — no início da página.

• Quatro contadores no topo: total de chamadas, hoje, erros, duração média da chamada em milissegundos.
• Top-10 ferramentas: quantas vezes chamadas, tempo médio, quantas delas terminaram em erro.
• Feed das últimas 50 chamadas: hora, shop_id, nome da ferramenta, duração, sucesso ou erro e texto do erro.
• Filtro por loja (/?shop=alpha) — os mesmos números para um único painel.
• No topo aparecem dois avisos: sobre ferramentas degradadas e sobre o fato de a última verificação da API Ozon ter encontrado problemas.

Lojas /shops

Os painéis são adicionados e removidos direto no navegador, sem editar arquivos e sem reiniciar o contêiner. O botão “Verificar” faz uma requisição real a ambas as APIs (POST /api/shops/{shop_id}/test) — as chaves são validadas na hora da adição, não no momento da primeira chamada de trabalho no meio de uma tarefa. Os tokens são criptografados com Fernet; a chave de criptografia fica em DATA_DIR/.encryption_key; na interface, as chaves aparecem mascaradas.

Diagnóstico /diagnostics

(na captura de tela — loja demo com chaves deliberadamente incorretas, por isso todas as sondas estão vermelhas)

• Para cada loja: se as chaves estão definidas, disponibilidade dos hosts da Ozon, 12 sondas de categorias da Seller API, verificação das chaves da Performance API.
• Verificação em segundo plano a cada HEALTH_CHECK_INTERVAL_MIN minutos (padrão 30, 0 — desativar) e 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 texto dos avisos. Na interface, são mostrados os últimos 30 registros; no banco, ficam armazenados até 1000 com rotação automática.
• Os mesmos dados estão disponíveis no chat pela ferramenta ozon_diagnostics.

Detector de degradações

O servidor percebe sozinho que a Ozon quebrou ou desativou um endpoint — não pela documentação e não pelo fato de uma tarefa ter falhado, mas pela própria estatística. Uma ferramenta cujas últimas três chamadas consecutivas terminaram em erro, mas antes tinham sucesso, entra na lista de degradações: ali é possível ver o nome da ferramenta, a hora da última chamada bem-sucedida, o número de erros consecutivos e o texto do último. No dashboard, isso é uma faixa vermelha; na página de diagnóstico, uma tabela. Prática: a alteração do lado da Ozon é visível no dia em que ocorre, e não uma semana depois, quando se descobre que os preços não foram atualizados. Pelo chat, a mesma lista é retornada pela ferramenta ozon_degradations.

JSON para monitoramento externo

Tudo o que está listado é coletado programaticamente, e não apenas visualmente:

Endpoint	O que retorna
GET /api/health	status do serviço, se a autorização está habilitada, últimas verificações, ferramentas degradadas
GET /api/stats	o mesmo resumo do dashboard; ?shop= — por loja
GET /api/diagnostics/{shop_id}	diagnóstico completo e ao vivo da loja

Assim, o servidor é integrado ao Zabbix, Uptime Kuma ou a um curl comum via cron.

Como funciona

Um único contêiner Docker, com um aplicativo FastAPI que combina o servidor MCP e a interface web.

• ozon_mcp/server.py — o próprio servidor MCP. A lista TOOLS descreve 151 ferramentas (nome, descrição, esquema JSON de argumentos), e o manipulador call_tool roteia a chamada para o método apropriado do cliente Ozon. Os clientes são armazenados em cache em um pool por shop_id, então alternar entre lojas não reconecta nada.
• ozon_mcp/client.py — dois clientes HTTP: OzonSellerClient (cabeçalhos Client-Id / Api-Key) e OzonPerformanceClient (token client_credentials, válido por 30 minutos e renovado automaticamente).
• ozon_mcp/app.py — FastAPI: endpoint /sse sobre SseServerTransport, verificação de token Bearer, páginas de dashboard, lojas e diagnóstico, tarefa em segundo plano de verificação de saúde.
• ozon_mcp/settings.py — lojas e chaves: criptografia Fernet, mascaramento para a UI, captura de chaves de variáveis de ambiente como loja default, migração do antigo settings.json de base única para shops.json.
• ozon_mcp/diagnostics.py — testes: ping nos hosts da Ozon, além de requisições reais leves em 12 categorias da Seller API e verificação de chaves da Performance API.
• ozon_mcp/stats.py — SQLite via aiosqlite: cada chamada de ferramenta com tempo e resultado, histórico de verificações de saúde, cálculo de degradações.

Hosts acessados pelo servidor:

API	URL base	Autorização
Seller API	api-seller.ozon.ru	cabeçalhos Client-Id e Api-Key
Performance API (publicidade)	api-performance.ozon.ru	OAuth client_credentials, token válido por 30 minutos

Pontos não óbvios:

• Lances e orçamentos de publicidade da Ozon são retornados em microrublos: 1000000 = 1 ₽. Não se surpreenda com números de sete dígitos.
• 403 em avaliações e perguntas não é uma falha, mas a ausência da assinatura Premium Plus. O diagnóstico não considera essas respostas como erro.
• As chaves da Ozon não contêm data de validade: a expiração só é visível pelo 401 nos testes.
• Estatísticas assíncronas de publicidade — um relatório por vez, ≤10 campanhas, ≤62 dias; a ferramenta aguarda a prontidão do relatório por até ~2 minutos.
• Status de solicitações de remessa na API v3 — números inteiros de 1 a 8, não strings.

Variáveis de ambiente

Variável	Padrão	Para quê
MCP_AUTH_TOKEN	vazio	Token Bearer para /sse. Vazio = sem autorização
HEALTH_CHECK_INTERVAL_MIN	30	intervalo do diagnóstico em segundo plano, 0 — desativar
PORT	8000	porta do servidor HTTP
DATA_DIR	/data	diretório com shops.json, stats.db, .encryption_key
OZON_CLIENT_ID, OZON_API_KEY	vazio	chaves da Seller API para a loja default, se não quiser inseri-las na UI
OZON_PERF_CLIENT_ID, OZON_PERF_CLIENT_SECRET	vazio	o mesmo para a Performance API

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

• Publicidade: criação de campanhas via API — apenas "Modelos" (CPC); orçamentos e lances em microrublos; não há método oficial para consultar o saldo do painel de publicidade.
• "Pagamento por pedido": lances fixos (desde fevereiro de 2025), apenas ativar e desativar.
• Avaliações, perguntas e parte da análise exigem assinatura Premium Plus (erro code 7).
• Métricas de funil em ozon_analytics estão marcadas como obsoletas pela Ozon — para posições na busca, use ozon_product_queries.
• /v3/finance/transaction/* serão desativados em 06.07.2026; a substituição já está integrada (ozon_finance_cash_flow, ozon_finance_accruals).
• ozon_product_stocks_by_warehouse usa v2, porque a v1 será desativada em 07.04.2026.
• Atos digitais de recebimento e transferência FBS foram removidos pela Ozon em 22.03.2026 — usa-se o ato comum.
• Não existe método "atualizar resposta a avaliação" na API da Ozon: a resposta é excluída e criada novamente.

A lista não foi montada reescrevendo a documentação: é um registro de degradações e cinco meses de chamadas diárias, conferidas com a documentação docs.ozon.ru em junho de 2026.

O que mudou na versão 2.0

Revisão completa para a API da Ozon de junho de 2026, com conferência por requisições reais: lista unificada de devoluções, cancelamentos v2, implementação v2, ship v4, supply-order v3, estratégias de preço reais e "Quero desconto", promoções próprias do vendedor, novo modelo de publicidade (modelos CPC + "Pagamento por pedido"), diagnóstico e detector de degradações, autorização do endpoint MCP.

Estrutura do projeto

ozon-mcp-server/
├── docker-compose.yml   # порт 8000, том ozon_data
├── Dockerfile           # python:3.12-slim, uvicorn
├── DEPLOY.md            # деплой на отдельную машину, перенос данных
├── docs/                # подключение клиентов + справочник инструментов
└── ozon_mcp/
    ├── server.py        # MCP-сервер: 151 инструмент, мульти-магазин
    ├── client.py        # Seller API + Performance API
    ├── app.py           # FastAPI: SSE, веб, авторизация, health-loop
    ├── diagnostics.py   # пробы категорий, детектор деградаций
    ├── settings.py      # магазины и ключи (Fernet)
    ├── stats.py         # статистика вызовов и история проверок (SQLite)
    └── templates/       # dashboard, diagnostics, shops

Implantação em uma máquina separada e transferência de lojas — DEPLOY.md.

O mesmo servidor para Wildberries

wb-mcp-server — a mesma ferramenta para a segunda plataforma: mesma arquitetura, mesma interface web com dashboard e diagnóstico, mesma multi-loja via shop_id, mesmo transporte SSE e as mesmas formas de conexão aos clientes.

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

Na prática, isso significa duas coisas:

• O segundo servidor é instalado sem novo aprendizado. Entendeu um — o segundo é iniciado seguindo esta mesma instrução; diferem a porta (8001 contra 8000) e o conjunto de ferramentas.
• É possível manter ambos na mesma máquina. As portas são diferentes, os dados ficam em volumes Docker distintos, sem conflito. No cliente, são apenas dois servidores MCP: ozon na http://localhost:8000/sse e wb na http://localhost:8001/sse.

A coexistência no mesmo servidor também não interfere nos limites: ambos acessam externamente pelo mesmo IP, mas Ozon e Wildberries contam limites cada um para si — são plataformas diferentes. A limitação de número de contas da seção sobre multi-loja vale separadamente para cada plataforma.

Atualizações e suporte

A Ozon muda a API constantemente: endpoints são adicionados, renomeados e desativados (na seção sobre limitações, está listado o que já foi capturado). Este servidor é uma ferramenta de trabalho do autor e é atualizado conforme a própria necessidade: quando uma mudança quebra algo em suas lojas. Mais de cinco meses de uso diário — e os commits aparecem quando a Ozon quebra algo, não em um cronograma. Uma pausa entre commits geralmente significa que tudo está funcionando. A vantagem dessa abordagem é que o código é testado pelo trabalho real todos os dias, e não publicado e esquecido; a desvantagem é que não há cronograma nem compromisso de prazos.

Se uma correção for necessária com urgência — escreva para d0371153@gmail.com. Issues e pull requests também são bem-vindos e analisados.

Licença

MIT — veja LICENSE.