Walmart MCP Server

Walmart MCP Server

Um servidor de Model Context Protocol (MCP) hospedado que oferece ao Claude, Cursor, Windsurf e qualquer outro cliente MCP três ferramentas somente leitura do Walmart. Execute uma busca por palavra-chave ou categoria, leia um item com o vendedor que detém o buy box e navegue pelas avaliações de clientes, tudo como JSON estruturado, sem conta de desenvolvedor no Walmart e sem nada para hospedar.

Ele lê páginas públicas do Walmart que um visitante desconectado pode ver, em walmart.com e walmart.ca.

1.000 créditos grátis todo mês, sem cartão de crédito, o que equivale a 100 chamadas ao Walmart na taxa de 10 créditos.

https://mcp.hasdata.com/api/mcp?apis=walmart

Conteúdo

• O que você precisa
• Início rápido
• Exemplos de prompts
• Ferramentas
• Erros e caminhos de falha
• Preços, plano gratuito e limites
• Seleção de ferramentas
• Comparação
• FAQ
• Links HasData
• Desenvolvimento
• Contribuição
• Licença

O que você precisa

Um cliente MCP e uma chave de API HasData do painel, gratuita para criar sem cartão, e o plano gratuito cobre cerca de 100 chamadas por mês na taxa de 10 créditos. Este é um servidor remoto, então o caminho mais simples é uma URL e um cabeçalho x-api-key, sem contêiner para executar. Um cliente que só fala stdio o acessa por meio de um launcher leve, publicado como @hasdata/walmart-mcp no npm e hasdata-walmart-mcp no PyPI, mostrado abaixo.

Início rápido

A URL do servidor é a mesma para todos os clientes. Nós o executamos na prática no Claude Code e no Claude Desktop. Os outros blocos seguem o formato documentado de cada cliente para um servidor remoto.

Clientes com suporte a OAuth podem adicionar a mesma URL como conector e entrar sem colocar uma chave em um arquivo de configuração.

claude mcp add --transport http walmart "https://mcp.hasdata.com/api/mcp?apis=walmart" \
  --header "x-api-key: HASDATA_API_KEY"

{
  "mcpServers": {
    "walmart": {
      "command": "npx",
      "args": ["-y", "@hasdata/walmart-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

{
  "mcpServers": {
    "walmart": {
      "command": "uvx",
      "args": ["hasdata-walmart-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

{
  "mcpServers": {
    "walmart": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=walmart",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

{
  "mcpServers": {
    "walmart": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=walmart",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

{
  "servers": {
    "walmart": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=walmart",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

Exemplos de prompts

Cada um destes cai em uma ferramenta, ou em duas em sequência quando a segunda precisa do ID do item que a primeira retorna.

• Encontre suportes para notebook abaixo de US$ 30 no Walmart e ordene por preço.
• Quanto custa o item 18493462688 agora, e quem detém o buy box?
• Mostre todos os outros vendedores que oferecem este item e quanto cobram com frete.
• Leia as avaliações deste item que mencionam duração da bateria.
• Traga apenas as avaliações de compra verificada deste item e resuma as reclamações.
• Compare o preço deste item em walmart.com e walmart.ca.

Um prompt que nomeia um produto em vez de um ID de item faz duas chamadas: uma busca para resolver o ID e uma consulta de produto para lê-lo. Avaliações funcionam da mesma forma, e o resultado da busca carrega o ID que ambas precisam.

Ferramentas

Três ferramentas, 10 créditos por chamada bem-sucedida. Cada uma recebe domain, seja walmart.com ou walmart.ca, e language, onde walmart.com atende en e es enquanto walmart.ca atende en e fr. Um idioma que a loja não oferece cai para o padrão dela.

IDs de item são específicos da loja. Em walmart.com são numéricos, como 18493462688, e em walmart.ca alfanuméricos, como 6NZMJ5CW6MH2. Um ID de uma loja não resolve na outra.

Obter resultados de busca do Walmart

hasdata_walmart_search_getSearchResults

Uma página de resultados de busca para uma palavra-chave, uma categoria, ou ambos.

Envie q para buscar, catId para navegar por uma categoria inteira, ou ambos para buscar dentro de uma. Nenhum aparece no array required do schema porque qualquer um dos dois satisfaz a chamada sozinho.

Retorna searchInformation, um array productResults, um bloco facets e pagination. Cada resultado carrega position, id, title, url, brand, isSponsored, badges, walmartPlusSavings, categoryPathId, um objeto price, reviews com rating e totalReviews, image, seller, availability e fulfillment.

O bloco facets é o mapa de cada filtro que a consulta suporta, e cada valor carrega a string exata para enviar de volta em facet. Executar uma busca sem filtro para ler os facets é mais barato do que adivinhar.

{
  "position": 1,
  "id": "18493462688",
  "title": "Incipio Portable Foldable Aluminum Laptop Stand and Riser with Adjustable Angles, Anti-Slip and Ventilated Design",
  "url": "https://www.walmart.com/ip/Portable-Laptop-Stand-Black/18493462688",
  "isSponsored": true,
  "badges": ["Overall pick"],
  "walmartPlusSavings": true,
  "categoryPathId": "4125_4134_1074326_9623037_7875081",
  "price": { "currentPrice": 9.96, "currentPriceDisplay": "$9.96" },
  "reviews": { "rating": 4.5, "totalReviews": 49 }
}

Obter detalhes do produto no Walmart

hasdata_walmart_product_getWalmartProduct

Um item completo.

Passe itemId ou url. Como na busca, nenhum é listado como obrigatório porque qualquer um funciona sozinho.

Retorna um objeto product com itemId, title, url, brand, brandUrl, type, model, upc, condition, badges, availability, um objeto price, o seller que detém o buy box, reviews, images, categoryPath, categoryPathId, highlights, specifications, keyItemFeatures, productDetails e fulfillment.

A chamada base já informa quantos concorrentes a página anuncia e o preço concorrente mais barato. Ative otherOffers apenas quando precisar das ofertas em si, porque isso faz uma segunda requisição ao Walmart e custa metade a mais.

{
  "itemId": "18493462688",
  "brand": "Incipio",
  "condition": "New",
  "price": { "currentPrice": 9.96, "currentPriceDisplay": "$9.96", "currency": "USD" },
  "seller": {
    "name": "Walmart.com",
    "id": "F55CDC31AB754BB68FE0B39041159D63",
    "returnPolicy": "Free 30-day returns"
  },
  "reviews": {
    "totalReviews": 49,
    "rating": 4.5,
    "fiveStars": 38,
    "fourStars": 4,
    "threeStars": 3,
    "twoStars": 1,
    "oneStar": 3
  },
  "specifications": [{ "name": "Maximum screen size", "value": "16 in" }],
  "fulfillment": {
    "type": "FC",
    "message": "Pickup, today at Fredericksburg Massaponax Supercenter",
    "deliveryDate": "2026-09-09T21:59:00.000Z"
  }
}

Obter avaliações de produto no Walmart

hasdata_walmart_reviews_getWalmartReviews

O feed de avaliações de um item, dez avaliações por página.

Retorna reviewsInformation, um array reviewResults, um bloco filters, appliedFilters e pagination.

filters é a parte que vale ler primeiro. Ela lista as classificações por estrelas, menções frequentes e condições pelas quais este item pode realmente ser filtrado, cada uma com uma contagem e com o value exato para enviar de volta. Dado {"name": "Battery Life", "value": "6049", "count": 8}, você envia aspectId: "6049" e espera oito avaliações. Adivinhar um ID de aspecto em vez de lê-lo aqui é o jeito usual de obter uma página vazia.

reviewsInformation carrega a classificação do item, a distribuição por estrelas, pontuações por aspecto e o resumo de avaliações por IA do Walmart. Também separa totalRatings de totalReviews, que importam separadamente: o item abaixo tem 49 classificações, mas apenas 21 avaliações escritas, e a paginação cobre as 21.

{
  "reviewsInformation": {
    "rating": 4.49,
    "totalRatings": 49,
    "totalReviews": 21,
    "recommendedPercentage": 100,
    "ratingBreakdown": { "fiveStars": 38, "fourStars": 4, "threeStars": 3, "twoStars": 1, "oneStar": 3 }
  },
  "reviewResults": [
    {
      "position": 1,
      "id": "434698083",
      "rating": 5,
      "title": "Good value laptop stand.",
      "text": "Good value for money. Not the sturdiest, but that is to be expected for a collapsible laptop stand. Overall gets the job done, I'd buy it again.",
      "date": "8/1/2026",
      "verifiedPurchase": true,
      "helpfulVotes": 0,
      "notHelpfulVotes": 0,
      "badges": ["Verified Purchase"],
      "seller": "Walmart.com",
      "language": "English",
      "aspects": [{ "id": "284", "polarity": "Positive" }]
    }
  ],
  "filters": [
    { "name": "Star rating", "parameter": "rating", "values": [{ "name": "5 stars", "value": "5", "count": 38 }] },
    { "name": "Frequent mentions", "parameter": "aspectId", "values": [{ "name": "Sturdiness", "value": "828", "count": 6 }] }
  ],
  "pagination": { "currentPage": 1, "reviewsPerPage": 10, "totalPages": 3, "totalResults": 21, "nextPage": 2 }
}

Erros e caminhos de falha

Planeje para estes casos em vez de assumir um caminho feliz.

Dois totais discordam em uma mesma resposta de busca, e ambos estão corretos. searchInformation.totalResultsDisplay é a string que o Walmart imprime na página, como "1000+", enquanto pagination.totalResults é o número por trás dela, como 8005. Um é texto de exibição e o outro é um inteiro, então não analise o primeiro nem imprima o segundo.

O Walmart para de servir resultados após aproximadamente a página 10. Além disso, a página volta vazia em vez de dar erro. Uma palavra-chave grande não pode ser enumerada por paginação, então restrinja com facet, uma faixa de preço ou uma categoria.

Os preços pertencem a uma loja, e a resposta diz qual. searchInformation.storeId a nomeia, e fulfillment.message a nomeia por extenso, até "Pickup, today at Fredericksburg Massaponax Supercenter". Comparar preços entre chamadas só faz sentido enquanto essa loja permanecer a mesma.

deliveryType: pickup é respondido contra uma única loja. Um item em estoque nacionalmente ainda pode voltar como indisponível, porque está indisponível naquela loja específica, não em todas.

A ferramenta de produto relata classificações onde você pode ler avaliações. O reviews.totalReviews dela é a contagem de classificações, 49 para o item acima, enquanto a ferramenta de avaliações relata 49 classificações e 21 avaliações escritas separadamente. Use a ferramenta de avaliações quando a distinção importar. As datas de revisão são strings M/D/YYYY. "8/1/2026" é o primeiro de agosto, não o oitavo de janeiro. Faça o parse com o formato em mãos, em vez de deixar uma biblioteca de datas adivinhar.

Uma avaliação pode trazer um id de aspecto ausente do filters. O bloco lista os tópicos pelos quais o item pode ser filtrado, que é uma lista mais curta do que os tópicos com os quais suas avaliações foram marcadas. Leia os aspectos da avaliação e filtre apenas com os ids que o bloco oferece.

variants está ausente, e não vazio, em um item sem variantes. Verifique a chave antes de lê-la.

Apenas um condition por solicitação. O parâmetro aceita um único valor, então uma consulta em duas condições exige duas chamadas.

Resultados que trazem dados também trazem um requestMetadata.id que vale citar como suporte.

Preços, camada gratuita e limites

Cada ferramenta Walmart custa 10 créditos por chamada bem-sucedida. Ativar o otherOffers adiciona 5 créditos à chamada de produto, 15 em vez de 10, então deixe-o desligado, a menos que as ofertas concorrentes sejam o objetivo. O tamanho da resposta não altera o preço.

A camada gratuita é 1.000 créditos todo mês, sem cartão, o que equivale a 100 chamadas Walmart na taxa base. Ela renova com o ciclo de cobrança, então um agente de baixo volume roda na camada gratuita indefinidamente.

Os planos pagos começam em US$ 49 por mês para 200.000 créditos, o que equivale a 20.000 chamadas. O preço unitário cai com o volume, de US$ 2,45 por 1.000 chamadas no plano inicial para US$ 1,00 no Business, US$ 0,84 no Growth e US$ 0,74 nos maiores planos de alto volume.

Seu plano também define a concorrência. A camada gratuita permite 1 solicitação por vez, Startup 15, Business 30, Growth 50, e os planos de alto volume vão de 200 a 1.500. Refaça a tentativa no erro 429 com backoff em qualquer processo não supervisionado, porque um agente que se espalha por vários ids de item atingirá o teto antes de você.

Uma solicitação que retorna um status diferente de 200 não é cobrada. Uma chamada bem-sucedida que não encontra nada ainda é uma chamada.

Seleção de ferramentas

Comece pelo que o prompt oferece. Uma palavra-chave ou categoria vai para a ferramenta de busca, um id de item vai direto para a ferramenta de produto ou avaliações. Gastar uma chamada de busca para chegar a um id que você já tem é o desperdício mais comum.

Depois, escolha pelo que a pergunta aborda. O resultado da busca é suficiente para rankings, varreduras de preço e análise de participação de prateleira em muitos itens. A ferramenta de produto é a única que traz especificações, o vendedor da buy box e a contagem de ofertas concorrentes. A ferramenta de avaliações é a única que traz o texto das avaliações.

Leia o bloco filters antes de filtrar. Uma chamada de avaliações sem filtro diz quais classificações, tópicos e condições existem e quantas avaliações cada um tem, o que transforma um filtro adivinhado em um filtro conhecido.

Como se compara

As APIs oficiais de Afiliados e Marketplace da Walmart são as rotas oficiais para esses dados, e elas respondem a perguntas diferentes.

A linha que decide é o escopo. Ambas as APIs oficiais respondem a perguntas sobre um catálogo com o qual você tem uma relação comercial, o que as descarta para monitorar um concorrente. Quando os itens são seus, a Marketplace API é autoritativa e gratuita, e você deve usá-la.

FAQ

Existe um servidor MCP oficial da Walmart?

A Walmart não publica um. Este é mantido pela HasData e lê páginas públicas da Walmart.

O que é um servidor MCP da Walmart?

Um servidor MCP expõe ferramentas que um cliente de IA pode chamar. Este transforma resultados de busca, páginas de item e feeds de avaliações da Walmart em JSON sobre o qual um agente pode raciocinar, sem precisar de navegador ou biblioteca de scraping na sua stack.

Preciso de uma conta Walmart ou de vendedor?

Não. A única credencial é a sua chave HasData.

Quais lojas são cobertas?

walmart.com e walmart.ca. Elas mantêm catálogos, ids de item, preços e moedas separados, então uma comparação entre lojas é uma comparação real, e não uma conversão de moeda.

Por que meu id de item não retornou nada?

Na maioria das vezes, porque ele pertence à outra loja. Um id numérico é walmart.com e um alfanumérico é walmart.ca, e nenhum resolve na outra. Passe domain para corresponder, ou passe o url completo e deixe que ele defina a loja.

Como obtenho as ofertas concorrentes?

Defina otherOffers na chamada de produto. Cada oferta retorna com o nome do vendedor, URL da loja, preço, condição, custo de envio, data de entrega e política de devolução. Custa 5 créditos a mais, porque exige uma segunda solicitação à Walmart.

Por que a mesma busca retorna preços diferentes em dias diferentes?

Em parte porque os preços mudam, e em parte porque a resposta é respondida contra uma loja Walmart específica, informada como searchInformation.storeId. Mantenha essa loja constante antes de ler uma mudança de preço como uma mudança de preço.

Posso usar isso junto com outras APIs HasData?

Sim. Uma chave cobre tudo, e um endpoint atende a todos por meio do parâmetro apis. Aponte um cliente para ?apis=walmart,amazon para obter os dois conjuntos de ferramentas em uma conexão, ou para mcp.hasdata.com/api/mcp para o catálogo completo.

A HasData é afiliada à Walmart?

Não. A HasData é um serviço independente e não é afiliada, endossada ou patrocinada pela Walmart. Walmart é uma marca registrada de seu respectivo proprietário. As ferramentas trabalham apenas com dados publicamente disponíveis, e você é responsável por usar os resultados em conformidade com os termos da Walmart e a lei aplicável a você.

Conformidade e dados pessoais

As avaliações trazem o nome do autor como o avaliador escolheu publicar, junto com um sinalizador de compra verificada. As entradas de vendedores do Marketplace trazem um nome comercial e uma URL de loja. Nenhum bloco precisa dos campos de autor para trabalho de sentimento ou preço, então descarte-os, a menos que seu propósito os exija, e verifique suas próprias obrigações antes de armazená-los.

Links HasData

• Documentação da API Walmart, os endpoints REST por trás dessas ferramentas
• Documentação do servidor MCP
• Preços
• Painel

Outros servidores MCP HasData: Google Search, Google Maps, Google Trends, Google Flights, DuckDuckGo, YouTube, TikTok, Instagram, Amazon, Shopify, Yelp, Zillow, Redfin, Airbnb, Booking.com, Indeed.

Desenvolvimento

O launcher é uma ponte stdio fina para o servidor remoto, então não há nada para compilar.

npm install
HASDATA_API_KEY=your_key_here npm test

Os testes em test/ verificam o contrato das ferramentas, a parte que pode quebrar sem um commit aqui. Eles verificam se ?apis=walmart retorna a contagem esperada de ferramentas, se nenhum nome mudou, se toda ferramenta ainda traz uma descrição, se os parâmetros de um-ou-outro documentados neste README ainda estão no schema, e se a chave em uso é realmente aceita. Essa última verificação chama uma ferramenta de verdade e custa 10 créditos, que é o preço de um canário que pode falhar pelo motivo certo.

Nenhuma das três ferramentas declara um parâmetro obrigatório, porque cada uma aceita um de dois insumos. A suíte fixa as alternativas em vez do array required, que passaria enquanto o schema não dissesse nada.

A suíte de contrato também roda semanalmente em um cronograma, porque a lista de ferramentas upstream pode mudar sem que ninguém toque neste repositório.

Contribuindo

Uma tabela de ferramentas, uma amostra de resposta ou um comportamento documentado que não corresponda à realidade merece uma issue. Há um modelo exatamente para isso. Pull requests são bem-vindos para o mesmo, e para qualquer coisa no launcher.

Licença

MIT, veja LICENSE.