mcp-yandex-merchants

Яндекс Товары MCP

A1 Яндекс Товары MCP conecta seu aplicativo de IA à API de parceiros do Яндекс Товары. Você pode alterar preços, descontos e a visibilidade de produtos individuais usando linguagem natural — sem editar ou reenviar todo o feed YML. A conexão começa diretamente no diálogo: não é necessário criar um token antecipadamente ou editar a configuração.

• 13 ações prontas. Conexão da conta diretamente no diálogo, verificação de acesso, lista de feeds, preços, descontos, ocultação e restauração de produtos, além de chamada direta aos demais métodos da API.
• Para um único produto e grandes listas. Em uma única solicitação, você pode alterar preços de 2.000 produtos ou ocultar e restaurar até 500 produtos.
• Alterações pontuais. O servidor trabalha com o feed YML já carregado e não recria feeds do zero.
• Resultado verificável. A gravação é considerada bem-sucedida somente quando status: "OK" na resposta do Яндекс Товары.
• Funciona localmente. O servidor é iniciado via npx; o token OAuth permanece no seu computador.

Experimente com a primeira mensagem:

Verifique a conexão com o Яндекс Товары e mostre os feeds disponíveis.

Conectar servidor · Ver cenários · Abrir documentação técnica

Veja o funcionamento em um minuto

Você: Verifique a conexão e mostre meus feeds.

Assistente: Verifica o token e mostra feedId e o endereço de cada feed disponível.

Você: No feed 1069, prepare um novo preço para o SKU-123: R$ 1.490 em vez de R$ 1.990. Primeiro mostre a alteração.

Assistente: Preparado: feed 1069, produto SKU-123, novo preço R$ 1.490, preço riscado R$ 1.990. Enviar a alteração?

Você: Sim, atualize.

Assistente: Envia a alteração e verifica o campo status na resposta. A operação é concluída se o Яндекс Товары retornar status: "OK".

Conteúdo

• Início rápido
• O que você pode solicitar
• Como funciona
• O que pode alterar dados
• Conexão e configuração
• Dados e telemetria
• Limitações
• Documentação técnica
• Suporte

Início rápido

Você precisará do Node.js 20 ou superior, de um feed YML carregado no Яндекс Товары e do login Yandex usado para carregar esse feed. O servidor é iniciado via npx, portanto não é necessário instalar o pacote separadamente.

1. Adicione o servidor ao aplicativo de IA — abaixo há um exemplo aberto para Codex; os demais aplicativos estão reunidos em instruções recolhíveis.
2. Escreva: «Conecte o Яндекс Товары». O assistente fornecerá um link para entrar no Yandex e pedirá que você envie o código de confirmação. Se você definiu YANDEX_MERCHANTS_OAUTH_TOKEN na configuração, esta etapa não é necessária.
3. Verifique a conexão: «Verifique a conexão com o Яндекс Товары e mostre os feeds disponíveis». Se o servidor retornar a lista de feeds, você pode prosseguir para preços e visibilidade dos produtos.

codex mcp add yandex-merchants -- npx -y mcp-yandex-merchants@latest

codex mcp list

claude mcp add --transport stdio --scope user yandex-merchants -- npx -y mcp-yandex-merchants@latest

claude mcp list

{
  "mcpServers": {
    "yandex-merchants": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-merchants@latest"]
    }
  }
}

{
  "mcpServers": {
    "yandex-merchants": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-merchants@latest"]
    }
  }
}

{
  "servers": {
    "yandex-merchants": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-merchants@latest"]
    }
  }
}

Este é um servidor MCP local: o aplicativo executa npx no seu computador. As versões web do ChatGPT e do Claude não conseguem iniciar esse processo por conta própria — use o aplicativo de desktop, a CLI ou um editor com suporte a servidores MCP locais.

O que você pode solicitar

Verificar a conexão e escolher um feed

• Verificar o token. Garantir que o servidor enxerga a conta — check_access.
• Mostrar feeds disponíveis. Obter feedId e o endereço de cada feed — list_feeds.

feedId será necessário para qualquer alteração. A API não mostra o conteúdo do feed, seu status ou os valores atuais dos produtos.

Alterar preços e descontos

• Alterar o preço de um único produto — set_offer_price.
• Atualizar preços em lote de até 2.000 produtos em uma única solicitação — update_offer_prices.
• Definir um desconto com preço novo e preço riscado — set_offer_discount.
• Adicionar um preço especial para Яндекс Пэй, СБП ou cartão Ozon — set_offer_price.

Os preços são informados apenas em rublos. Se houver várias ofertas com o mesmo id em um feed, a API alterará apenas a primeira.

Ocultar ou restaurar produtos

• Ocultar um único produto — hide_offer.
• Ocultar até 500 produtos com um único comando — hide_offers.
• Restaurar até 500 produtos para exibição — show_offers.

Um produto pode ser ocultado por tempo indeterminado ou por até 720 horas. Na ocultação por tempo indeterminado, ele permanecerá invisível até um comando separado de restauração.

Chamar os demais métodos da API

raw_request permite acessar um método da API de parceiros para o qual não existe uma ação pronta separada. Ele suporta GET, POST e DELETE e aceita dados no formato original da API.

raw_request pode alterar dados reais. Se a ação desejada já existir entre as ferramentas prontas, é mais seguro usá-la.

Os nomes completos dos campos, formatos de resposta e códigos de erro estão reunidos na referência de ferramentas.

Como funciona

O servidor não cria, exclui nem carrega feeds. Ele usa feedId de um feed YML já existente e envia ao Яндекс Товары alterações pontuais para os produtos indicados.

Isso é útil quando você precisa rapidamente:

• corrigir um ou vários preços;
• aplicar um desconto;
• ocultar um produto esgotado;
• restaurar um produto para exibição.

O feed YML em si continua sendo gerenciado pelo painel do Яндекс Товары ou pelo Вебмастер. O servidor não consegue ler o conteúdo do feed, portanto os ids dos produtos e o histórico de alterações devem ser mantidos do seu lado.

O que pode alterar dados

O servidor reduz o risco de erros da seguinte forma:

• verifica campos obrigatórios, tamanhos de listas, comprimento do id, preços positivos e faixa de desconto antes de enviar a solicitação;
• verifica status no corpo da resposta, pois HTTP 200 ainda não significa gravação bem-sucedida;
• não repete a gravação automaticamente após erro do servidor ou perda de conexão;
• não permite que raw_request envie o token OAuth para um endereço externo;
• informa ao aplicativo de IA quais ações leem dados e quais os alteram.

A confirmação antes da gravação depende do aplicativo de IA. Se quiser verificar os valores primeiro, peça ao assistente para preparar a alteração, mostrar feedId, o id do produto e os novos valores, e executá-la somente após o próximo comando.

Conexão e configuração

Para uso comum, o token não é necessário antecipadamente:

1. No chat, peça para conectar o Яндекс Товары.
2. Abra o link do Yandex OAuth estritamente com o login Yandex usado para carregar o feed YML — o token de outro login não verá nenhum feed.
3. Confirme o acesso e envie o código ao assistente. O código é de uso único e válido por 10 minutos.

O servidor usa PKCE: o código do chat não pode ser trocado por um token por conta própria — apenas o seu servidor em execução pode fazer isso. Ele solicita uma única permissão — products:partner-api («API de busca de produtos»). O token obtido é armazenado localmente em ~/.config/mcp-yandex-merchants/credentials.json com permissões apenas para o proprietário e é renovado automaticamente. Não é necessário reiniciar o aplicativo de IA após o login.

Para verificar o estado, peça «mostre o status da conexão»; para desconectar, peça «desconecte o Яндекс Товары». O acesso concedido pode ser revogado no Яндекс ID.

Para CI e instalações não padronizadas, a configuração por variáveis de ambiente está disponível:

Se você usar seu próprio aplicativo OAuth, registre-o em oauth.yandex.ru/client/new (plataforma «Web services», Redirect URI https://oauth.yandex.ru/verification_code) e adicione o acesso products:partner-api — «API de busca de produtos». O token pronto para YANDEX_MERCHANTS_OAUTH_TOKEN é emitido pela página https://oauth.yandex.ru/authorize?response_type=token&client_id=<ClientID>, aberta com o login que carregou o feed YML. Guarde o token como uma senha: não adicione configuração com token real ao Git e não a envie a terceiros.

Dados e telemetria

O servidor é executado no seu computador e acessa diretamente https://yandex.ru/products/api/ext/partner. O token OAuth é adicionado apenas às solicitações dessa API: até mesmo raw_request aceita um caminho relativo e não pode enviar o token para outro site. No login via diálogo, o servidor também acessa oauth.yandex.ru — apenas para trocar o código de confirmação por um token e renová-lo. Por padrão, o servidor envia para usage.gistrec.cloud telemetria técnica anônima: um identificador de instalação aleatório, nome do evento ou ferramenta, versão do pacote, versão do Node.js, sistema operacional e informações sobre o cliente de IA conectado. Ela não inclui token OAuth, dados da conta, IDs de feeds e produtos, preços, argumentos de ferramentas ou textos de consultas. O envio é feito em segundo plano e não afeta o funcionamento do servidor.

Para desativar a telemetria para servidores MCP A1, defina a variável de ambiente:

ASKADS_TELEMETRY=0

Limitações

• Não é possível ler o estado atual dos produtos. A API não retorna preços atuais, lista de produtos ocultos, conteúdo ou status do feed. Mantenha um registro de alterações do seu lado.
• Não é possível gerenciar os próprios feeds. Criar, excluir ou recarregar um feed YML só pode ser feito no painel ou no Webmaster.
• Apenas rublos. A API não aceita outras moedas.
• ID do produto — até 50 caracteres. Identificadores mais longos não são aceitos pela API.
• Até 2.000 preços por requisição. Para ocultar e restaurar — até 500 produtos por requisição.
• Até 50.000 operações por minuto. Alterações de preço e o total de ocultações com restaurações são contabilizados separadamente.
• Sem rollback automático. Após uma queda de conexão, o resultado da gravação pode permanecer desconhecido, e não é possível ler o estado por meio desta API. Não repita essa operação automaticamente.
• Sem monitoramento contínuo. O servidor funciona apenas quando o aplicativo de IA o chama. Se o aplicativo suportar tarefas agendadas, é possível pedir que ele verifique periodicamente a disponibilidade ou execute um cenário predefinido.

Documentação técnica

• Catálogo de recursos MCP — páginas sobre tarefas de usuário para cada ferramenta.
• Todas as ferramentas — parâmetros, respostas, códigos de erro e limitações.
• Documentação de desenvolvimento — execução local, verificações e build.
• Publicação — lançamento do pacote npm e publicação nos catálogos MCP.
• Pacote no npm.
• API Yandex Products.

Suporte

Encontrou um erro ou falta algum cenário? Crie uma issue ou escreva para o Telegram.