marketplaces-mcp-ru — Wildberries & Ozon Seller APIs

marketplaces-mcp-ru: Wildberries, Ozon, Яндекс Маркет e Авито no seu assistente de IA

🇬🇧 English version

Conecta o assistente de IA (Claude, Cursor, Codex, Cowork e outros) diretamente aos seus painéis da Wildberries, Ozon, Яндекс Маркета e Авито. Você pergunta em linguagem natural, e o agente busca vendas, pedidos, estoques, preços, finanças e avaliações direto da API do marketplace (WB Seller API, Ozon Seller API, Yandex Market Partner API, Avito API), sem inventar números.

Para que serve

Você vende em várias plataformas, mas os dados ficam em painéis diferentes. Vendas, estoques, preços, finanças, avaliações: tudo manualmente, um por um, em vários navegadores. Um assistente de IA comum ajuda pouco aqui. Ou navega pelo navegador e esbarra no captcha, ou apresenta números que soam confiantes, mas são inventados.

Este projeto resolve o problema de outra forma. Ele dá ao assistente acesso direto à API das quatro plataformas:

• Os números vêm da resposta da Wildberries, Ozon, Яндекс Маркета e Авито, com indicação da fonte e dos campos. Não é um resumo, não é um palpite.
• Antes de alterar preço ou estoque, o agente pede confirmação. Não dá para "derrubar o preço três vezes" por acidente.
• Nada de navegador e captcha: a consulta é feita pelo token do painel diretamente.

Pergunte em linguagem natural: "mostre as vendas da semana em todas as plataformas", "o que devo reencomendar", "compare meus preços com o mercado". O agente escolhe o método certo ou um cenário pronto e conduz passo a passo.

⚠️ Versão alpha. Ajuda na operação do vendedor, mas é uma ferramenta, não um substituto para o analista. O núcleo verificado manualmente (vendas, estoques, preços, finanças, avaliações) foi validado em painéis reais. Os demais métodos foram importados das especificações e servem como mapa para exploração. Detalhes na seção Ressalvas.

O que você pode perguntar

Basta escrever para o agente no chat em russo:

покажи продажи за неделю на WB и Ozon и сравни
какие заказы на Яндекс Маркете ждут отгрузки сегодня
подтверди новые заказы Авито Доставки и покажи, где кончается остаток
что пора дозаказать, посчитай дни покрытия по остаткам и продажам
вытащи финотчёт реализации WB за прошлый месяц
какие товары на Ozon с красным индексом цены
собери отзывы ниже 4 звёзд за неделю и сгруппируй жалобы по товару
сделай ABC-анализ по выручке и покажи товары-хвост

Não sabe por onde começar? Diga "o que você sabe fazer no meu painel". O agente mostrará os cenários prontos: para Wildberries são pulso de vendas, saúde do estoque, auditoria de preços, planejador de recompra, análise ABC, resumo de avaliações; para Ozon: risco de out-of-stock, análise de preços, economia unitária, sincronização de catálogo, auditoria de conteúdo e também ABC e avaliações; para Яндекс Маркета: risco de out-of-stock, análise de preços, análise de avaliações, índice de qualidade; para Авито: pedidos para confirmação, saúde dos anúncios, gastos versus resultado, análise de avaliações. Cada cenário é uma receita passo a passo com interpretação do resultado e erros típicos.

Instalação

Um guia detalhado para qualquer público está em QUICKSTART.md. Várias formas, o mesmo resultado.

1. Claude Desktop em um clique (.mcpb). Pegue o marketplaces-mcp-ru-v<версия>.mcpb do GitHub Releases e clique duas vezes — o Claude Desktop instala a extensão sozinho e pede as chaves na janela de configurações. Sem terminal e sem Gatekeeper. Um único pacote sobe WB + Ozon + Ozon Performance + Яндекс Маркет + Авито de uma vez.
2. Peça ao seu próprio IA (sem terminal). Abra o Claude ou o Cowork e diga: "instale o marketplaces-mcp-ru". O agente conduz pelo skill integrado install-skill/. No sandbox do Cowork, o clique final fica com você; no Claude Code, a instalação é totalmente automática.
3. Baixar e clicar. Pegue o marketplaces-mcp-ru-v<версия>.zip do GitHub Releases, descompacte, clique duas vezes em install.command (macOS) ou install.bat (Windows) e cole as chaves. No macOS, no primeiro uso: clique com o botão direito → "Abrir" → "Abrir" (isso contorna o Gatekeeper para arquivos baixados).
4. Pelo terminal. git clone https://github.com/ilyautov/marketplaces-mcp-ru, depois python3 install.py --client <ваш-клиент>.
5. Para desenvolvedores (npx / uvx). npx -y marketplaces-mcp-ru — a mesma linha dos configs de todos os clientes MCP; não é preciso instalar Python, o launcher via npm baixa automaticamente o uv e a versão correta do PyPI. uvx marketplaces-mcp-ru inicia o servidor unificado direto do PyPI; os servidores individuais são iniciados pelos comandos de console wb-mcp / ozon-mcp / ozon-perf-mcp / yandex-mcp / avito-mcp. As chaves são definidas por variáveis de ambiente ou pelos mesmos *_add_cabinet do chat.
6. VS Code / Cursor em um clique. Os botões "instalar" acima deste texto abrem o editor e registram o uvx marketplaces-mcp-ru no config MCP dele; o VS Code já pede as chaves na hora, no Cursor elas são inseridas no JSON aberto.
7. Docker. docker run -i --rm -e WB_API_TOKEN=… -e OZON_CLIENT_ID=… -e OZON_API_KEY=… ghcr.io/ilyautov/marketplaces-mcp-ru — o mesmo servidor unificado via stdio, sem Python na máquina. Essa imagem é a que está no MCP Registry como pacote OCI. Para acesso remoto, adicione -e MCP_TRANSPORT=http -e MCP_HTTP_HOST=0.0.0.0 -p 8000:8000: o servidor sobe em http://…:8000/mcp (Streamable HTTP). O modo HTTP não tem autenticação própria; proteja-o com proxy ou firewall.

O instalador copia o aplicativo para uma pasta estável (~/.marketplace-mcp/app) e vincula o config a ela, então a pasta original pode ser movida ou excluída depois sem quebrar nada. Nada de pip install nem edição manual de JSON: as dependências são instaladas sozinhas no primeiro uso. Você só precisa das chaves. Há suporte a 4 clientes via --client: claude-desktop e opencode recebem o config pronto, claude-code e codex recebem os comandos prontos mcp add.

Onde obter as chaves. Wildberries: seller.wildberries.ru → Configurações → Acesso à API. Ozon: seller.ozon.ru → Configurações → Chaves de API. Яндекс Маркет: partner.market.yandex.ru → Configurações → Acesso à API (Api-Key). Авито: avito.ru → Para negócios → Integrações → API (client_id + client_secret). As chaves ficam armazenadas em ~/.marketplace-mcp/cabinets.json localmente (chmod 600) e não vão para o repositório nem para o chat. Você pode conectar várias lojas e alternar entre elas direto do chat (*_add_cabinet / *_use_cabinet).

Verificação após a instalação: um único comando mostra, para todos os cinco servidores, quantas ferramentas e métodos foram carregados, se as chaves foram encontradas e onde (painel / env), e com --live faz uma chamada real de leitura em cada painel.

python3 serve.py doctor --live          # из клона
uvx marketplaces-mcp-ru doctor --live   # из PyPI
npx -y marketplaces-mcp-ru doctor --live  # то же через npm, без Python

Código de retorno 0 significa que todos os painéis configurados responderam. Segredos não aparecem na saída.

Segurança

A chave do painel mexe em preços, estoques e dinheiro, então cada método já vem classificado por nível de risco:

• read: leitura, executado imediatamente;
• write: alteração, exige confirm_write=true;
• destructive: exclusão, exige confirm_write=true e i_understand_this_modifies_data=true.

A verificação roda localmente; nada sai para fora sem confirmação. Para garantir que um método de mutação não seja marcado por engano como read, há um teste no CI (test_safety_catalog.py): a build falha se um PUT, PATCH ou DELETE entrar no catálogo com nível read. Além disso, o call_method protege em tempo real: mesmo uma marcação desatualizada read em uma requisição de mutação não rebaixa a verificação abaixo de write.

Mais detalhes em SECURITY.md. Se encontrar uma vulnerabilidade, escreva para ilyautov@gmail.com com o assunto SECURITY: marketplaces-mcp-ru, sem abrir issue público.

Como funciona

Por baixo dos panos há cinco servidores MCP (Wildberries, Ozon Seller, Ozon Performance, Яндекс Маркет, Авито) sobre um núcleo comum. Em vez de "uma ferramenta para cada endpoint" (seriam 300+ ferramentas, nas quais o agente se perde), a abordagem é diferente: 8 meta-ferramentas universais sobre um catálogo de métodos. Cobertura total da API com uma superfície compacta.

ваш ИИ-агент
      │
      ▼
 8 мета-инструментов  ──►  каталог (endpoints.yaml)  ──►  общее ядро
 search / describe /                                      клиент · safety · ошибки
 call / call_raw /                                        пагинация · реестр
 fetch_all / ...                                                │
 + типизированные инструменты (wb_get_sales, …)                 ▼
                          Wildberries / Ozon / Яндекс Маркет / Авито HTTPS API

As meta-ferramentas são as mesmas em todos os servidores (prefixo wb_, ozon_, ozon_perf_, ym_ ou avito_):

Ferramenta	O que faz
*_check_auth	Verifica se as chaves existem (não imprime segredos)
*_search_methods	Busca um método em russo ou inglês
*_describe_method	Descrição completa: método, host, caminho, escopo, nível de risco, limite, link para a doc
*_call_method	Chama qualquer método do catálogo passando pela verificação de segurança
*_call_raw	Chama qualquer caminho, mesmo que ainda não esteja no catálogo (cobertura total)
*_fetch_all	Auto-paginação (offset / last_id / cursor / cursor de data WB / pageToken do Маркета / page do Авито)

Além disso, há ferramentas tipadas para tarefas frequentes (wb_get_sales, wb_get_stocks, ozon_get_products, ozon_get_prices, ym_get_orders, ym_set_price, avito_get_orders, avito_update_stock e outras) e ferramentas de gerenciamento de painéis.

O catálogo é montado a partir das especificações oficiais OpenAPI:

Catálogo	Arquivo	Métodos	Seções
Wildberries	wb_mcp/endpoints.yaml	307	70
Ozon Seller	ozon_mcp/endpoints.yaml	441	67
Ozon Performance (publicidade)	ozon_mcp/perf_endpoints.yaml	45	6
Яндекс Маркет (Partner API)	yandex_mcp/endpoints.yaml	165	29
Авито (API para negócios)	avito_mcp/endpoints.yaml	64	8

O núcleo (vendas, estoques, preços, finanças, avaliações) foi validado ao vivo; o restante foi importado das especificações, e o call_raw busca o que ainda não está no catálogo. Cobertura por área de negócio:

Área	Wildberries	Ozon
Vendas e pedidos	vendas, pedidos, tarefas de separação FBS / DBS / DBW / Retirada	pedidos FBO / FBS, envios, devoluções
Estoques e armazéns	estoques, armazéns do vendedor, entregas FBS	estoques por armazém, FBO / FBS, análise de estoque
Preços e descontos	preços e descontos, calendário de promoções	preços, estratégias de precificação, promoções
Finanças	relatório financeiro de vendas, saldo	transações, acúmulos, vendas, compensações
Conteúdo e fichas	fichas, categorias, características, mídia	produtos, atributos, categorias, certificados
Avaliações e perguntas	avaliações, perguntas	avaliações (exige Premium Plus), perguntas e respostas
Publicidade	gestão de campanhas, estatísticas	Performance API (servidor separado)

Яндекс Маркет e Авито (adicionados na 0.5.0):

Área	Яндекс Маркет	Авито
Pedidos	pedidos FBS / DBS / Express, status, devoluções, remessas	pedidos da Авито Доставка, confirmação, códigos de rastreio, marcação
Produtos e estoques	catálogo, fichas, estoques por armazém, produtos ocultos	anúncios, estoques nos anúncios, upload automático
Preços	preços, quarentena de preços, promoções, recomendações	preço do anúncio
Avaliações e chats	avaliações, perguntas, chats com compradores	classificação, avaliações e respostas, mensageiro
Análise	estatísticas de pedidos e produtos, 27 relatórios, índice de qualidade	visualizações e contatos, gastos, ligações
Promoção	boost de vendas, lances	serviços de promoção, BBIP
Análise	funil de vendas, relatórios	relatórios analíticos, giro de estoque

A lista completa de seções é exibida pelo *_list_sections direto no chat; a busca pontual é feita pelo wb_search_methods("остатки").

Desenvolvimento

Seção para quem quer explorar o código, validar métodos na prática ou enviar um PR.

Estrutura. Toda a lógica comum fica em core/; os servidores são camadas finas sobre ela:

core/                общее ядро всех серверов
  client.py          HTTPS-клиент (хосты, заголовки, ретраи)
  credentials.py     загрузка ключей из cabinets.json / env
  safety.py          гейт read / write / destructive
  registry.py        загрузка и индексация каталога endpoints.yaml
  paginate.py        авто-пагинация (offset / last_id / cursor / date / pageToken / page)
  entities.py        нормализация сущностей (товары, заказы и т.д.)
  workflows.py       движок пошаговых сценариев
  tools.py           регистрация мета-инструментов в MCP
  transport.py       выбор транспорта: stdio (по умолчанию) или Streamable HTTP
  doctor.py          диагностика: инструменты, каталоги, ключи, живой пинг
  errors.py          единый формат ошибок
wb_mcp/              сервер WB: server.py + endpoints.yaml + workflows.yaml
ozon_mcp/            сервер Ozon: server.py + endpoints.yaml + perf_endpoints.yaml + workflows.yaml
ozon_perf_mcp/       сервер Ozon Performance (реклама, OAuth2)
yandex_mcp/          сервер Яндекс Маркета: server.py + endpoints.yaml + workflows.yaml
avito_mcp/           сервер Авито: server.py + endpoints.yaml + workflows.yaml (OAuth2)
scripts/             сборка каталогов, валидация, релиз
tests/               офлайн-тесты (токены не нужны)

Execução local e testes. É necessário Python 3.10+. As dependências (mcp, httpx, pyyaml) são instaladas pelo serve.py em um .venv local no primeiro uso.

git clone https://github.com/ilyautov/marketplaces-mcp-ru.git
cd marketplaces-mcp-ru

# офлайн-тесты, ключи не нужны — все офлайн-тесты зелёные
env -u OZON_CLIENT_ID -u OZON_API_KEY -u WB_API_TOKEN python3 -m pytest tests/ -q

# selfcheck серверов: 21 тул для wb, 21 для ozon, 16 для ozon-perf, 22 для yandex, 26 для avito
python3 serve.py wb --selfcheck
python3 serve.py ozon --selfcheck
python3 serve.py ozon-perf --selfcheck
python3 serve.py yandex --selfcheck
python3 serve.py avito --selfcheck

# всё сразу: инструменты, каталоги, ключи, живой пинг кабинетов
python3 serve.py doctor --live

# образ для MCP Registry / удалённого запуска
docker build -t marketplaces-mcp-ru .
docker run --rm marketplaces-mcp-ru doctor

Transporte. O padrão é stdio, como esperam Claude Desktop, Cursor, Codex e Claude Code. O MCP_TRANSPORT=http alterna qualquer um dos servidores (e o unificado) para Streamable HTTP: MCP_HTTP_HOST (padrão 127.0.0.1), MCP_HTTP_PORT (8000), MCP_HTTP_ALLOWED_HOSTS — lista de cabeçalhos permitidos Host separados por vírgula, proteção contra DNS-rebinding ao publicar externamente. O modo HTTP não tem autenticação: quem alcançar a porta trabalha com as suas chaves. Mantenha-o em localhost ou atrás de um proxy. Como o catálogo funciona e cresce. endpoints.yaml é montado schema-driven a partir das especificações oficiais OpenAPI: ingest_specs.py (WB) e ingest_ozon.py (Ozon) puxam os caminhos, derive_pagination.py e fix_items_path_from_examples.py configuram a paginação e items_path, sync_swagger.py busca as specs mais recentes. O registro de cada método descreve operation_id, método, host, caminho, escopo, nível de risco e paginação. A importação é idempotente e aditiva: níveis de risco e descrições curados não são sobrescritos. validate_items_path.py é um validador ao vivo (rode localmente com suas chaves), package_release.py gera um zip versionado limpo, smoke_mcp.py é um teste de fumaça.

O que é especialmente útil enviar:

• Verificação prática dos verbos HTTP. Os caminhos dos métodos importados são confiáveis, mas os verbos não: testes ao vivo encontraram "GET" que na verdade são POST (405). Corrija */endpoints.yaml e anexe uma prova: código de resposta ou link para a documentação.
• Novos cenários em */workflows.yaml: receitas passo a passo com interpretação e erros típicos, cada etapa verificada contra o catálogo.
• Esclarecimento da classificação de segurança, se um método estiver marcado de forma muito branda ou estrita.

Regras completas em CONTRIBUTING.md. Antes do PR, rode os testes offline e --selfcheck de todos os servidores; se mudou o número de métodos ou ferramentas, ajuste os números no README.

Segurança do repositório. Diretrizes para pessoas e agentes estão em AGENTS.md. Segredos vivem apenas localmente: .env, cabinets.json, chaves e certificados são protegidos por .gitignore, e o pre-commit executa scripts/security/forbid_sensitive_files.py e scan_mcp_config.py. Que um método mutável não entre no catálogo com nível read é garantido pelo teste test_safety_catalog.py: a build falha em PUT, PATCH ou DELETE com a marcação read. O arquivo .mcp.json é rastreado de propósito, é o manifesto do plugin sem segredos.

Perguntas frequentes

Preciso saber programar? Não. Existe a opção "peça ao seu IA" e a opção de instalação com duplo clique. pip install e edição de JSON não são necessárias, as dependências são instaladas sozinhas, você só precisa da chave da API.

Isso é seguro? Para onde vão as chaves? O servidor roda onde seu agente está, localmente. As chaves ficam em ~/.marketplace-mcp/cabinets.json (chmod 600), não vão para o repositório nem para o chat. Qualquer alteração no painel (preço, estoque) só acontece com sua confirmação.

Por que isso é melhor que parsers e bots de navegador? É a Seller API direta por token, não uma raspagem de páginas web: sem captcha, sem bloqueios, dados estruturados. Além disso, proteção contra alteração acidental de preço ou estoque.

É gratuito? Sim, código aberto sob licença MIT. Pegue, faça fork, melhore.

Funciona com Yandex Market e Avito? Sim, desde a versão 0.5.0. Yandex Market conecta via Api-Key do painel do parceiro (Partner API: pedidos, produtos, estoques, preços, relatórios, chats, índice de qualidade). Avito — via par client_id / client_secret da seção "Integrações" (pedidos Avito Delivery, estoques e preços de anúncios, estatísticas, avaliações, mensageiro, promoção). Os servidores yandex-mcp e avito-mcp funcionam tanto separadamente quanto no pacote combinado.

O que é MCP e por que um vendedor precisa disso? MCP (Model Context Protocol) é um padrão aberto pelo qual um assistente de IA conecta ferramentas externas. Este projeto é um servidor MCP para marketplaces: transforma as APIs de Wildberries, Ozon, Yandex Market e Avito em ferramentas que o agente chama sozinho, a partir da sua pergunta em russo.

Ressalvas

Confira com a documentação viva dos marketplaces:

• WB Authorization: o servidor envia o token bruto sem o prefixo Bearer (confirmado na prática). Se a autenticação falhar, verifique isso primeiro.
• Métodos importados das especificações: caminhos confiáveis, verbos HTTP nem sempre. Testes ao vivo encontraram métodos marcados como GET que na verdade são POST (resposta 405). Trate esses registros como mapa para exploração: confirme o verbo e o corpo pela documentação ou chame via call_raw. O núcleo curado (7 categorias WB, 4 seções Ozon) e o conjunto verificado ao vivo são confiáveis.
• Ozon varia entre versões (list v3, attributes v4, prices v5). Em caso de 404, verifique a versão; ingest_ozon.py realinha os caminhos.
• Ozon Performance: por enquanto é artefato de catálogo mais integração OAuth pela documentação. O contrato do endpoint de token não foi verificado ao vivo, são necessárias credenciais de anúncios.
• Yandex Market e Avito (novo em 0.5.0): catálogos montados a partir de documentos OpenAPI oficiais, ferramentas tipadas escritas conforme a especificação, mas ainda sem execução ao vivo em contas reais. Erros em nomes de campos são possíveis; describe_method e call_raw ajudam a corrigir a requisição na hora.
• O painel sobrescreve variáveis de ambiente. O painel ativo em cabinets.json tem prioridade sobre o env. 401 inexplicável ou "Client-Id should be positive integer": verifique esse arquivo primeiro.

O que isto não é

É uma ferramenta para agente de IA, não um serviço online "em um clique" nem um substituto para analista. A decisão que altera preços, estoques ou dinheiro é sempre sua; a proteção apenas evita que isso aconteça por acidente. O projeto está em estágio alpha: instale, teste com seus dados, experimente. Encontrou um problema, abra uma issue (sem chaves reais ou dados do painel).

A arquitetura aproveitou ideias fortes de marketplace-MCP maduros (catálogo schema-driven, verificação de segurança, formato de erro unificado, auto-paginação), mas implementada com código próprio, sem dependência de bibliotecas de terceiros.

Licença

MIT.