Wildberries MCP Server

WB MCP Server

Gerencie suas lojas Wildberries pelo chat com um assistente de IA. 202 ferramentas da Seller API — cartões, preços, publicidade, entregas, avaliações, finanças, análise — disponíveis para Claude, Cursor, Copilot, Gemini CLI e qualquer outro cliente MCP. Para vendedores WB com um ou vários painéis e sem vontade de clicar no painel no que pode ser pedido por palavras.

Vende também na Ozon? Existe um servidor igual para Ozon.

O servidor está em uso diário há mais de cinco meses, em cerca de vinte painéis WB, 202 ferramentas. É uma ferramenta de trabalho pessoal do autor e é atualizada conforme a própria necessidade — como exatamente.

Ты: Какие мои карточки заблокированы и почему?
Ты: Покажи ДРР по всем кампаниям за неделю и выключи те, где он выше 15%.
Ты: На каких складах коэффициент приёмки сейчас 0 или 1?
Ты: Ответь на все новые отзывы с оценкой 5 благодарностью.

O que ele faz

202 ferramentas, agrupadas por seções da Wildberries Seller API. Lista numerada completa com descrição de cada uma — em docs/tools.md.

Três coisas que normalmente não existem em servidores semelhantes:

• Multi-loja. Cada chamada aceita shop_id, então dois painéis WB convivem em um único diálogo. Se houver apenas uma loja — shop_id pode ser omitido.
• Diagnóstico da API WB. O servidor faz ping nos hosts da WB, faz requisições leves de teste em cada categoria, analisa a validade e as permissões do token e destaca "degradações": uma ferramenta que funcionava antes e agora falha consistentemente — sinal claro de que a WB mudou a API.
• Criptografia de tokens. Os tokens WB ficam criptografados (Fernet), e não no config do cliente.

Início rápido

Opção 1: um único comando, sem Docker

O servidor funciona via stdio — é assim que Claude Desktop, Cursor, VS Code e outros clientes MCP o conectam. Não é preciso compilar nada:

uvx wb-mcp-server

Ou via pip:

pip install wb-mcp-server
wb-mcp

Configuração do cliente (por exemplo, claude_desktop_config.json):

{
  "mcpServers": {
    "wildberries": {
      "command": "uvx",
      "args": ["wb-mcp-server"],
      "env": {
        "WB_API_TOKEN": "ваш токен Wildberries API",
        "DATA_DIR": "~/.wb-mcp"
      }
    }
  }
}

DATA_DIR aponte para qualquer diretório gravável — ali ficam 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 WB e adição fácil de lojas pelo navegador. Será necessário Docker (Docker Desktop ou OrbStack) e um token da Wildberries Seller API.

git clone https://github.com/DeviceIngineering/wb-mcp-server.git
cd wb-mcp-server
cp .env.example .env          # для локального запуска можно оставить как есть
docker compose up -d --build

Verificação:

curl -s http://localhost:8001/api/health
# {"status":"ok","auth_enabled":false,"health_check_interval_min":30,...}

O que abre:

Depois:

1. Abra http://localhost:8001/shops → Adicionar loja → cole o token WB → Verificar. O token é obtido no portal do vendedor: Configurações → Acesso à API → Criar token (validade de 180 dias, o restante aparece na página de diagnóstico).
2. Conecte o cliente MCP — veja a próxima seção.
3. Pergunte ao assistente: "mostre a lista das minhas lojas na Wildberries" — deve funcionar a ferramenta wb_list_shops.

Análise do comando de execução:

Parar: docker compose down (os dados permanecem no volume wb_data). Logs: docker compose logs -f.

git clone https://github.com/DeviceIngineering/wb-mcp-server.git
cd wb-mcp-server
python3 -m venv .venv && source .venv/bin/activate
pip install .
DATA_DIR=./data PORT=8001 python -m wb_mcp.app

Instalação nos clientes

O servidor entrega MCP via SSE: GET /sse — fluxo de eventos, POST /messages — mensagens do cliente. O suporte a SSE varia entre clientes, então há uma instrução específica para cada um — com caminhos de config no macOS, Linux e Windows, JSON pronto e opções com e sem token.

Visão geral e tabela de compatibilidade — docs/README.md.

Onde o cliente tem um comando que configura a conexão sozinho, a instrução começa por ele, e a edição do JSON vem como segundo método. A opção mais curta — Claude Code:

claude mcp add --transport sse wildberries http://localhost:8001/sse
claude mcp list      # ожидается: wildberries ... ✔ Connected

Multi-loja e segurança

Vários painéis. As lojas são adicionadas em /shops, cada uma recebe seu shop_id. A ferramenta wb_list_shops retorna a lista; 200 das 202 ferramentas aceitam shop_id como primeiro parâmetro (exceções — wb_list_shops e wb_degradations). Se houver apenas uma loja, o parâmetro pode ser omitido: o servidor usa a única disponível.

O sentido não é "saber lidar com duas contas", mas que a estratégia é escrita uma vez e aplicada a todos os painéis: regra de preço, modelo de resposta a avaliações, teto de lance em publicidade se aplicam a todas as lojas em um único diálogo — sem trocar de conta e sem espalhar chaves pelos configs de diferentes clientes. Quantos painéis podem ser conectados. Não há limite no código: shops.json é um dicionário comum, adicione quantos quiser. O teto não é definido pelo servidor, mas pela Wildberries: todos os painéis acessam a WB a partir do mesmo endereço IP — o do servidor — e os limites são contados também por endereço. Estimativa do autor: cerca de vinte painéis por um endereço ficam na zona segura. Além disso — distribuir por vários servidores com endereços diferentes.

Por que isso é mais importante do que parece, vê-se nos limites da WB: vários métodos têm 3 requisições por minuto, e qualquer resposta 4XX conta como 10 requisições. Com dez painéis em um servidor, algumas requisições incorretas seguidas consomem o limite dez vezes mais rápido — e esbarram nele todas as lojas de uma vez, não apenas a que errou.

Há como monitorar isso:

• Diagnóstico em segundo plano envia um /ping por host por execução (limite — 3 requisições em 30 segundos por host) e acumula verificações falhas e avisos no histórico. A aproximação do limite é visível antes, não depois do bloqueio.
• Detector de degradações distingue dois casos: degradação simultânea de muitas ferramentas — é throttling por endereço; degradação de uma — quebrou um endpoint específico da WB. No dashboard isso se vê de relance.

Onde ficam os tokens. No volume wb_data (dentro do contêiner — /data):

• shops.json — lojas, tokens criptografados com Fernet;
• .encryption_key — chave de criptografia, gerada no primeiro uso;
• stats.db — SQLite com estatísticas de chamadas e histórico de diagnóstico.

A chave fica ao lado dos dados criptografados, então a criptografia protege contra vazamento acidental de um único arquivo shops.json (backup, copiar e colar), mas não contra quem obteve acesso ao volume inteiro. Os dados devem ser transferidos com o volume completo — veja DEPLOY.md.

Autorização MCP. Variável MCP_AUTH_TOKEN em .env:

openssl rand -hex 32   # значение вписать в .env → MCP_AUTH_TOKEN=
docker compose up -d

• vazio (padrão) — /sse aberto a todos que tenham acesso de rede à porta;
• definido — o cliente deve enviar Authorization: Bearer <токен> ou ?token=<токен> na URL. A segunda opção ajuda clientes que não suportam cabeçalhos arbitrários.

O token é verificado nos dois endpoints MCP — tanto em GET /sse quanto em POST /messages.

O que o servidor não faz:

• A interface web (/, /shops, /diagnostics) não é protegida por token — fica acessível a todos que tenham acesso de rede à porta.
• A porta 8001 não foi feita para exposição à internet. Para acesso externo — Tailscale ou VPN.
• O servidor não termina HTTPS. Para acesso externo via TLS — use um reverse proxy.

Interface web: cada chamada visível

Em um servidor MCP comum, as chamadas vão para o nada: o que exatamente o assistente fez, quanto levou e o que o marketplace respondeu — não se vê, e o problema só aparece quando algo não funciona. Aqui, cada chamada tem registro, e cada loja tem estado. Para uma ferramenta que gerencia dinheiro real na loja, isso é condição de confiança, não enfeite. Em cinco meses de uso diário em vinte painéis, essas páginas acumularam o que está listado na seção sobre limites da WB.

Dashboard — /

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

Resumo de todas as chamadas de ferramentas (stats.get_summary()):

• total de chamadas, chamadas hoje, número de erros, duração média de chamada;
• top-10 ferramentas: quantas vezes chamadas, tempo médio, quantos erros;
• feed das últimas 50 chamadas: hora, loja, ferramenta, duração em milissegundos, sucesso ou erro, texto do erro;
• filtro por loja — alternador "Todas / painel específico" acima do resumo.

Lojas — /shops

Os painéis são adicionados e removidos diretamente no navegador, sem editar arquivos ou reiniciar o contêiner. Cada loja tem um botão «Verificar»: ele faz uma requisição real leve ao WB e diz imediatamente se o token está vivo — em vez de deixar para descobrir isso no momento da primeira chamada de trabalho. Na lista, os tokens são exibidos mascarados (abc***xyz).

Os tokens são criptografados com Fernet e ficam em shops.json dentro do volume de dados; a chave — em .encryption_key no mesmo local. O pool de clientes HTTP é redefinido ao salvar e excluir uma loja, então o novo token é captado imediatamente.

Diagnóstico — /diagnostics

(na captura de tela — loja de demonstração com token fictício: o WB responde 401 a cada ping e a cada teste, então a página inteira fica vermelha. É assim que uma verificação malsucedida se parece — o servidor está funcionando corretamente. Com um token válido, a linha «Verificação …» mostra ping 13/13, пробы 20/20, e o status da loja — «✅ Saudável».)

Verificação em segundo plano a cada HEALTH_CHECK_INTERVAL_MIN minutos (padrão: 30), para cada loja:

• token — prazo de validade, categorias de acesso, flags «somente leitura» e «sandbox»;
• ping em 13 hosts da API do WB — disponibilidade e latência de cada um;
• 20 testes — um GET real leve por categoria de API. São eles que capturam a situação «endpoint retorna 404 porque o WB o renomeou»;
• avisos em linguagem humana: «o token expira em N dias», «Conteúdo: 404 em /content/v2/... — talvez o WB tenha alterado a API»;
• histórico de verificações com rotação automática (são mantidos os últimos 1000 registros);
• botão «Verificar agora» — executar tudo imediatamente.

Detector de degradações

O mais útil que a estatística acumulada oferece. O servidor encontra sozinho as ferramentas que funcionavam antes e agora falham de forma consistente: as últimas três chamadas são erros, embora tenha havido chamadas bem-sucedidas no histórico. Para cada uma dessas ferramentas, são exibidos o horário da última chamada bem-sucedida, o número de erros consecutivos, o texto do último erro e o momento em que tudo quebrou.

Ou seja, o servidor detecta pela própria estatística que o Wildberries quebrou ou desativou um endpoint — e avisa antes de você esbarrar nisso no trabalho. Ao lado da seção sobre limites e prazos de desativação de endpoints, isso é a continuação prática: lá está listado o que o WB já anunciou; aqui, o que ele fez silenciosamente.

Você pode ver no painel ou pela ferramenta wb_degradations — direto do chat.

JSON para monitoramento externo

Tudo o que é visível também pode ser coletado por máquina:

Assim, você pode colocar o servidor no Uptime Kuma, Zabbix ou qualquer outro monitoramento e descobrir sobre um token quebrado antes que o assistente conte.

Como isso funciona

Um único contêiner Docker, com um aplicativo FastAPI que combina dois papéis: servidor MCP via SSE e uma pequena interface web. Um arquivo por parágrafo:

• wb_mcp/server.py — o próprio servidor MCP. A lista TOOLS de 202 objetos Tool (nome, descrição, esquema JSON de argumentos) é o que o cliente recebe em resposta a tools/list. As chamadas são distribuídas por três dicionários: NO_CLIENT_DISPATCH (sem acesso ao WB), CLIENT_DISPATCH (precisa do cliente HTTP da loja), SHOP_DISPATCH (precisa também de shop_id). Aqui também fica o ponto de entrada stdio main() — para o caso de um cliente que só suporta stdio.
• wb_mcp/client.py — clientes HTTP dos 14 hosts do Wildberries. Um WBClient por loja, com httpx.AsyncClient e token; os clientes são armazenados em cache em um pool por shop_id.
• wb_mcp/app.py — FastAPI: GET /sse e POST /messages para MCP, páginas do painel, lojas e diagnóstico, API JSON /api/*, verificação MCP_AUTH_TOKEN, loop em segundo plano de verificações de saúde.
• wb_mcp/settings.py — lojas e chaves: leitura e gravação de shops.json, criptografia Fernet, migração do antigo settings.json de um único painel, mascaramento de tokens para a interface. Há um fallback: se a variável WB_API_TOKEN for definida, a loja default aparece.
• wb_mcp/diagnostics.py — ping nos hosts do WB, decodificador de token JWT (validade, permissões, sandbox), «testes» — uma requisição real leve por categoria de API, notícias do WB.
• wb_mcp/stats.py — SQLite via aiosqlite: cada chamada de ferramenta é registrada com horário, sucesso e shop_id; é daqui que vêm o detector de degradações e o histórico de verificações de saúde.
• wb_mcp/templates/ — três páginas em PicoCSS, sem build de frontend.

Pontos não óbvios:

• shop_id é preenchido automaticamente enquanto houver apenas uma loja. Prático no dia a dia, mas ao adicionar um segundo painel, as requisições sem shop_id começarão a retornar «Informe o shop_id».
• Cada chamada é registrada na estatística, inclusive as que falharam. É daí que o detector de degradações funciona: «funcionava antes, agora falha de forma consistente» — sinal de mudança na API do WB, não um erro seu. Para ver: ferramenta wb_degradations ou painel.
• O diagnóstico em segundo plano a cada 30 minutos faz requisições reais ao WB e consome limites. Se atrapalhar — defina HEALTH_CHECK_INTERVAL_MIN=0 em .env.
• As respostas são retornadas como estão, JSON bruto do WB, sem reempacotamento. As ferramentas são previsíveis por causa disso, mas relatórios grandes devem ser solicitados com filtros, senão a resposta consome o contexto.
• POST /messages é montado como um aplicativo ASGI separado (Mount), e não como uma rota comum do FastAPI: handle_post_message envia a resposta ASGI por conta própria, e dentro de uma rota o framework a enviaria uma segunda vez — a conexão quebraria a cada POST. Por isso, a autorização para esse endpoint é verificada manualmente dentro do aplicativo.
• A versão da biblioteca mcp está fixada como >=1.0.0,<2. O servidor foi escrito para a API de decoradores do mcp 1.x (@app.list_tools()); no mcp 2.0 ela foi removida. Não remova o limite superior em pyproject.toml: com mcp 2.x o servidor falha na inicialização com AttributeError: 'Server' object has no attribute 'list_tools'.

Variáveis de ambiente

Limitações da API do Wildberries

Estas são limitações do próprio WB, não do servidor — mas o assistente vai esbarrar nelas regularmente, e é melhor conhecê-las com antecedência. A lista não foi montada reescrevendo a documentação: são cinco meses de chamadas diárias em cerca de vinte painéis, mais o registro de diagnóstico.

• GET /adv/v3/fullstats (estatísticas de publicidade) — 3 requisições por minuto, período máximo de 31 dias.
• Funil de vendas v3 — 3 requisições por minuto; histórico diário disponível apenas para a última semana.
• /ping — 3 requisições em 30 segundos por host (o diagnóstico em segundo plano leva isso em conta).
• Qualquer resposta 4XX é contabilizada pelo WB como 10 requisições no limite (regra desde 04.06.2026). Um parâmetro incorreto em um loop — e você atingiu o limite.
• reportDetailByPeriod é removido em 15.07.2026; o servidor já usa finance-api com fallback para o endpoint antigo.
• A criação de remessas FBW pela API é impossível — apenas no painel pessoal. As ferramentas wb_fbw_* são informativas.
• O token do WB dura 180 dias. O restante é exibido por wb_token_info e pela página /diagnostics.
• A resposta 429 do WB é um limite, não uma falha. Tente novamente em um minuto.

Conferido com a documentação em dev.wildberries.ru em junho de 2026.

Referência técnica

Hosts da Wildberries Seller API

Diagnóstico

• Página /diagnostics — para cada loja: prazo de validade do token e suas permissões, ping em todos os hosts da API do WB, testes por categoria, histórico de verificações, botão «Verificar agora».
• Verificação automática em segundo plano a cada HEALTH_CHECK_INTERVAL_MIN minutos.
• Detector de degradações — destaca no painel as ferramentas que pararam de funcionar.
• Ferramentas MCP: wb_diagnostics, wb_token_info, wb_degradations, wb_api_news.
• GET /api/health — resumo JSON para monitoramento externo.
• POST /api/diagnostics/run — executar a verificação de todas as lojas agora.
• GET /api/diagnostics/<shop_id> — diagnóstico completo de uma única loja.

Estrutura do projeto

wb-mcp-server/
├── docker-compose.yml          # порт 8001, том wb_data
├── Dockerfile                  # python:3.12-slim
├── pyproject.toml
├── DEPLOY.md                   # деплой на отдельную машину, перенос данных
├── docs/                       # подключение клиентов + справочник инструментов
└── wb_mcp/
    ├── server.py       # MCP-сервер: 202 инструмента, диспетчеризация, stdio-режим
    ├── client.py       # HTTP-клиенты 14 API Wildberries
    ├── app.py          # FastAPI: SSE + веб-интерфейс + авторизация + health-loop
    ├── diagnostics.py  # ping, JWT-декодер, пробы, новости API
    ├── settings.py     # магазины и ключи (Fernet)
    ├── stats.py        # статистика вызовов и история проверок (SQLite)
    └── templates/      # PicoCSS: dashboard, diagnostics, shops

Implantação

Coloque o servidor em uma máquina separada, transfira as lojas, configure a inicialização automática — veja DEPLOY.md.

O mesmo servidor para Ozon

DeviceIngineering/ozon-mcp-server — a mesma ferramenta para outro marketplace: mesma arquitetura, mesma interface web com painel e diagnóstico, mesma multi-loja via shop_id, mesmo transporte SSE e as mesmas formas de conexão com clientes. Se você entendeu um, o segundo é iniciado pelo mesmo guia; diferem a porta e o conjunto de ferramentas.

Você pode mantê-los simultaneamente na mesma máquina: as portas são diferentes, os dados ficam em volumes Docker distintos, não há conflito.

A coexistência no mesmo servidor também não interfere nos limites: ambos acessam a internet pelo mesmo IP, mas Wildberries e Ozon contam os limites cada um para si — são plataformas diferentes. A restrição quanto ao número de painéis, mencionada na seção sobre multi-loja, vale separadamente para cada plataforma.

Atualizações e suporte

O Wildberries muda a API constantemente: endpoints são adicionados, renomeados e desativados — na seção sobre limitações está listado o que já foi capturado na prática. Este servidor é uma ferramenta de trabalho do autor: mais de cinco meses de uso diário em cerca de vinte painéis. Ele é atualizado conforme a necessidade do próprio autor: quando uma mudança quebra algo em suas lojas, e não em um cronograma. Por isso, os intervalos entre commits podem ser longos — isso significa que o WB não quebrou nada nesse período. Não há compromisso de prazos.

Se uma correção for urgente — escreva para d0371153@gmail.com. Issues e pull requests também são bem-vindos e são analisados.

Licença

MIT — veja LICENSE.