mcp-yandex-dostavka

 Яндекс Доставка MCP

A1 Яндекс Доставка MCP permite gerenciar entregas corporativas a partir do Claude, Codex, Cursor e outros aplicativos de IA. Você define a tarefa em palavras comuns, e o assistente acessa sua conta da Яндекс Доставка, calcula o custo, cria envios e mostra o status deles.

• No mesmo dia pela cidade. Calcule a entrega, chame um courier, veja a localização dele e obtenha um link para o destinatário.
• No dia seguinte e pela Rússia. Compare os prazos disponíveis e o custo da entrega até a porta.
• Em pontos de retirada (ПВЗ) e lockers. Encontre um ponto adequado, calcule as opções e finalize a entrega escolhida.
• Primeiro o cálculo, depois o pedido. O assistente distingue o custo preliminar, a preparação do envio e o momento em que a entrega é realmente confirmada.
• Sem integração própria. Já inclui 16 ações prontas, esquemas de dados e regras para lidar com segurança com requisições repetidas.

É adequado para empresas e empreendedores que já estão conectados à API B2B da Яндекс Доставка e receberam um token no painel de controle. Não é um serviço para remetentes particulares.

Descubra o custo rapidamente

Você: Calcule a entrega de uma caixa de 2 kg da Lva Tolstogo, 16 para Tverskaya, 7.

Assistente: Verifiquei a rota pela Яндекс Доставка e retornei o custo atual, a distância e o tempo aproximado de chegada da sua conta.

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

Veja o funcionamento em um minuto

Você: Calcule a entrega de um buquê hoje até as 18:00 do escritório na Lva Tolstogo, 16 para o cliente na Tverskaya, 7.

Assistente: Verifiquei a rota e obtive o custo preliminar, a distância e o ETA da sua conta da Яндекс Доставка.

Você: Finalize a entrega se o preço final não passar de 1 000 ₽.

Assistente: O preço final está dentro do limite. A entrega foi confirmada e a busca por um courier começou.

Você: Onde está o courier agora e qual link devo enviar ao destinatário?

Assistente: Obtive a posição atual do courier e o link público para rastrear o pedido.

Você: Agora encontre opções de entrega desta caixa para Kazan no dia seguinte: até a porta, em um ПВЗ ou locker.

Assistente: Obtive as opções disponíveis com prazos e custos. Para ПВЗ e lockers, mostrarei endereços, horários e formas de pagamento suportadas.

Você: Posso cancelar a primeira entrega gratuitamente?

Assistente: Primeiro verifiquei as condições de cancelamento. Mostrarei se ele está disponível agora, se será gratuito e qual valor será cobrado no cancelamento pago.

Os exemplos mostram a sequência de ações disponíveis. Preços, prazos, status e disponibilidade específicos sempre vêm da sua conta da Яндекс Доставка.

Conteúdo

• Início rápido
• O que você pode delegar
• Como o assistente trabalha com entregas
• Quando um pedido real é criado
• Obtendo acesso à API
• Configurações técnicas
• Dados e telemetria
• Limitações
• Documentação técnica
• Ajuda e feedback

Início rápido

Você precisa do Node.js 20+ e de um token de cliente corporativo da Яндекс Доставка.

1. Obtenha o token no painel de controle da Яндекс Доставка.

2. Adicione o servidor MCP ao seu aplicativo de IA.

mcp-yandex-dostavka é executado no seu computador via npx, portanto, as versões de navegador do ChatGPT e do Claude não podem conectá-lo diretamente.

codex mcp add yandex-dostavka \
  --env YANDEX_DELIVERY_TOKEN=ваш_токен \
  -- npx -y mcp-yandex-dostavka@latest

codex mcp list

{
  "mcpServers": {
    "yandex-dostavka": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-dostavka@latest"],
      "env": {
        "YANDEX_DELIVERY_TOKEN": "ваш_токен"
      }
    }
  }
}

claude mcp add \
  --env YANDEX_DELIVERY_TOKEN=ваш_токен \
  --transport stdio \
  --scope user \
  yandex-dostavka \
  -- npx -y mcp-yandex-dostavka@latest

claude mcp list

{
  "mcpServers": {
    "yandex-dostavka": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-dostavka@latest"],
      "env": {
        "YANDEX_DELIVERY_TOKEN": "ваш_токен"
      }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "yandex-delivery-token",
      "description": "Токен Яндекс Доставки",
      "password": true
    }
  ],
  "servers": {
    "yandex-dostavka": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-dostavka@latest"],
      "env": {
        "YANDEX_DELIVERY_TOKEN": "${input:yandex-delivery-token}"
      }
    }
  }
}

Após conectar, abra um novo diálogo no aplicativo escolhido e peça:

Calcule a entrega de uma caixa de 2 kg da Lva Tolstogo, 16 para Tverskaya, 7.

O que você pode delegar

Entrega no mesmo dia pela cidade

• Descobrir o custo. Calcular preço, distância e tempo aproximado de chegada do courier com base em endereços, peso e dimensões do envio.
• Criar um envio. Enviar mercadorias, endereços, contatos e requisitos de veículo ou courier.
• Encontrar um pedido. Buscar envios por status, telefone, período ou número de pedido da sua empresa.
• Acompanhar o courier. Obter a posição atual dele e o link público para o destinatário.
• Cancelar com consequências conhecidas. Primeiro, descobrir se o cancelamento é possível e se será pago.

Entrega no dia seguinte e pela Rússia

• Comparar opções. Obter os intervalos disponíveis e o custo da entrega até a porta.
• Finalizar a opção escolhida. Confirmar o prazo, o método de entrega e o preço adequados.
• Verificar o pedido. Descobrir o status atual e ver o histórico de alterações.
• Cancelar o pedido. Enviar uma solicitação de cancelamento enquanto o status atual permitir.

Entrega em ПВЗ e lockers

• Encontrar um ponto adequado. Buscar ПВЗ e lockers por cidade, coordenadas, tipo e forma de pagamento.
• Verificar as condições. Ver endereço, horário, disponibilidade de autoenvio e formas de pagamento.
• Calcular e finalizar. Obter opções de entrega para o ponto escolhido e confirmar a adequada.

Como o assistente trabalha com entregas

Para entrega no mesmo dia, o assistente primeiro calcula a rota. Quando você pede para criar um envio, ele envia os dados para a Яндекс Доставка, aguarda a avaliação final e inicia a busca por um courier. Depois disso, você pode consultar o status, ver a posição do courier e obter o link de rastreamento.

Para entrega no dia seguinte, pela Rússia, em ПВЗ ou locker, o assistente obtém as opções disponíveis com prazos e custos. Você escolhe a opção adequada, e o assistente finaliza o pedido e pode ler o status atual e o histórico.

Os valores não são inventados. Custo, ETA, intervalos disponíveis, endereços dos pontos e status vêm da sua conta da Яндекс Доставка.

O assistente não monitora pedidos constantemente. Ele verifica o estado da entrega quando você define uma tarefa. Se o aplicativo de IA suportar tarefas agendadas, você pode configurar verificações regulares na interface — por exemplo, consultar o status do pedido a cada hora até a entrega.

Quando um pedido real é criado

Um comando explícito para finalizar ou cancelar autoriza a ação correspondente. O comportamento de confirmações adicionais depende do aplicativo de IA: alguns clientes pedem permissão antes de cada gravação, outros seguem suas próprias políticas.

Obtendo acesso à API

1. Registre-se como cliente corporativo em dostavka.yandex.ru e assine o contrato. Para entrega no dia seguinte, pela Rússia, em ПВЗ e lockers, também conecte uma estação de expedição.
2. No painel de controle, abra a aba «Интеграции» e clique em «Получить токен».
3. Envie o token para o servidor em YANDEX_DELIVERY_TOKEN.

O token não expira, mas deixa de funcionar após a alteração da senha do painel de controle. Saiba mais: acesso à API de entrega no mesmo dia e acesso à API de entrega em outro dia.

O token é armazenado em texto simples na configuração do aplicativo de IA. Trate-o como uma senha e não adicione configurações com token real ao Git.

Um ou dois tokens

Normalmente, um YANDEX_DELIVERY_TOKEN geral é suficiente. Se diferentes tipos de entrega estiverem conectados em painéis diferentes, defina dois tokens separados:

• YANDEX_DELIVERY_EXPRESS_TOKEN — token de entrega no mesmo dia;
• YANDEX_DELIVERY_PLATFORM_TOKEN — token de entrega em outro dia, pela Rússia, em ПВЗ e lockers.

Se não houver um token geral, o servidor precisará de ambos os tokens separados.

Ambiente de teste

O ambiente de teste existe apenas para entrega em outro dia, pela Rússia, em ПВЗ e lockers. Defina YANDEX_DELIVERY_PLATFORM_BASE_URL=https://b2b.taxi.tst.yandex.net e use os dados de teste da instrução oficial. Ele processa apenas endereços de Moscou.

Para entrega no mesmo dia, não há ambiente de teste: é seguro verificar o cálculo de custo e a leitura de solicitações existentes, mas os envios criados entram no sistema de produção.

Configurações técnicas

No nível técnico, o servidor trabalha com duas partes independentes da API B2B da Yandex Delivery: a API de entrega no mesmo dia e a API de entrega para outro dia. Elas podem ter tokens diferentes, endereços de servidores, formatos de dinheiro e unidades de medida — o servidor MCP seleciona os parâmetros necessários por conta própria.

* O token geral não é necessário se ambos os tokens separados forem definidos.

Dados e telemetria

Solicitações à Yandex Delivery

O servidor é executado localmente e acessa a API da Yandex Delivery diretamente. O token Bearer é adicionado apenas às solicitações da API selecionada. Até mesmo a ferramenta universal aceita um caminho relativo: se ele levar a um servidor externo, a solicitação é bloqueada para que o token não seja enviado a um endereço de terceiros.

Telemetria anônima

Por padrão, o servidor envia para usage.gistrec.cloud três tipos de eventos técnicos: inicialização do servidor, nome da ferramenta chamada e código do motivo da inicialização sem token configurado.

O evento inclui um identificador aleatório de instalação, versão do pacote, nome e versão do aplicativo de IA, versão do Node.js e sistema operacional. O token, dados da conta, argumentos das ferramentas e textos das solicitações não são lidos nem enviados. O envio é feito em segundo plano com tempo limite de 2 segundos e não afeta o funcionamento do servidor.

Para desativar a telemetria para servidores MCP A1, adicione à configuração:

ASKADS_TELEMETRY=0

A implementação está em src/telemetry.ts.

Limitações

• Não é somente leitura. O assistente pode criar e cancelar entregas reais; o cancelamento pode ter custo.
• O aplicativo de IA influencia as confirmações. O servidor MCP informa o tipo de cada ação, mas a decisão sobre uma pergunta adicional antes da gravação é do aplicativo e de seu agente.
• Não há ambiente de teste para entrega no mesmo dia. É possível verificar com segurança o cálculo de custo e a leitura de solicitações existentes.
• Não há monitoramento contínuo. O servidor funciona durante a chamada do aplicativo de IA. Se o aplicativo suportar tarefas agendadas, configure a verificação regular de status na interface dele.
• Pode haver atraso em caso de limitação temporária. O servidor aguarda e repete a solicitação por conta própria. Se a Yandex Delivery continuar indisponível, tente novamente mais tarde.
• Não há reversão automática. A possibilidade e o custo do cancelamento dependem do status atual e das regras da Yandex Delivery.

Documentação técnica

• Catálogo de 16 recursos MCP — páginas individuais das ferramentas no idioma das tarefas do usuário.
• Referência técnica das ferramentas — dados de entrada, respostas, status, erros, formatos de dinheiro e unidades de medida.
• Desenvolvimento — execução local, verificações, build e smoke-test seguro.
• Publicação — lançamento do pacote npm e listagem nos catálogos MCP.
• Pacote npm — versão publicada mcp-yandex-dostavka.
• API de entrega no mesmo dia e API de entrega em outro dia — documentação oficial da Yandex Delivery.

Ajuda e feedback

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

Você leu até o final!