walmart-mcp

# Walmart MCP Server

<!-- mcp-name: com.hasdata/walmart -->

A hosted Model Context Protocol (MCP) server that gives Claude, Cursor, Windsurf and any other MCP client three read-only Walmart tools. Run a keyword or category search, read one item with the seller holding the buy box, and page through its customer reviews, all as structured JSON, with no Walmart developer account and nothing to host.

It reads public Walmart pages that a signed-out visitor can see, on `walmart.com` and `walmart.ca`.

**1,000 free credits every month, no card required**, which is 100 Walmart calls at the 10-credit rate.

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

[![Glama score](https://glama.ai/mcp/servers/HasData/walmart-mcp/badges/score.svg)](https://glama.ai/mcp/servers/HasData/walmart-mcp)
[![tool contract](https://github.com/HasData/walmart-mcp/actions/workflows/contract.yml/badge.svg)](https://github.com/HasData/walmart-mcp/actions/workflows/contract.yml)
[![MCP](https://img.shields.io/badge/MCP-remote%20%7C%20streamable%20HTTP-6366f1?style=flat-square)](https://mcp.hasdata.com/api/mcp?apis=walmart)
[![Tools](https://img.shields.io/badge/tools-3-10b981?style=flat-square)](#tools)
[![npm](https://img.shields.io/npm/v/@hasdata/walmart-mcp?style=flat-square&logo=npm&label=npm&color=cb3837)](https://www.npmjs.com/package/@hasdata/walmart-mcp)
[![PyPI](https://img.shields.io/pypi/v/hasdata-walmart-mcp?style=flat-square&logo=pypi&logoColor=white&label=PyPI&color=3775a9)](https://pypi.org/project/hasdata-walmart-mcp/)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)

## Contents

- [What you need](#what-you-need)
- [Quick start](#quick-start)
- [Example prompts](#example-prompts)
- [Tools](#tools)
- [Errors and failure paths](#errors-and-failure-paths)
- [Pricing, free tier and limits](#pricing-free-tier-and-limits)
- [Tool selection](#tool-selection)
- [How it compares](#how-it-compares)
- [FAQ](#faq)
- [HasData links](#hasdata-links)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)

## What you need

An MCP client and a HasData API key from the [dashboard](https://app.hasdata.com/sign-up?utm_source=github&utm_medium=syndication&utm_campaign=walmart-mcp), free to create with no card, and the free tier covers about 100 calls a month at the 10-credit rate. This is a remote server, so the simplest path is a URL and an `x-api-key` header, with no container to run. A client that only speaks stdio reaches it through a thin launcher, published as `@hasdata/walmart-mcp` on npm and `hasdata-walmart-mcp` on PyPI, shown below.

## Quick start

The server URL is the same for every client. We run it hands-on in Claude Code and Claude Desktop. The other blocks follow each client's own documented format for a remote server.

| Field | Value |
| :--- | :--- |
| URL | `https://mcp.hasdata.com/api/mcp?apis=walmart` |
| Transport | HTTP, streamable |
| Auth header | `x-api-key: HASDATA_API_KEY` |

Clients with OAuth support can add the same URL as a connector and sign in without putting a key in a config file.

<details>
<summary><b>Claude Code</b></summary>

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

</details>

<details>
<summary><b>Claude Desktop</b></summary>

Settings, then Connectors, then Add custom connector, then paste `https://mcp.hasdata.com/api/mcp?apis=walmart` and sign in.

For the config-file route, Claude Desktop loads only local (stdio) servers, so it reaches a remote server through a stdio launcher. The `@hasdata/walmart-mcp` package is that launcher, and it reads the key from the environment. Add this to `claude_desktop_config.json`:

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

For Python instead of Node, swap the launcher for the PyPI package, which `uvx` runs without a manual install:

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

</details>

<details>
<summary><b>Cursor</b></summary>

`~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one:

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

</details>

<details>
<summary><b>Windsurf</b></summary>

`~/.codeium/windsurf/mcp_config.json`. Windsurf calls the field `serverUrl`, not `url`:

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

</details>

<details>
<summary><b>VS Code</b></summary>

`.vscode/mcp.json` in the workspace:

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

</details>

## Example prompts

Each of these lands on one tool, or on two in sequence when the second needs the item id the first returns.

- Find laptop stands under $30 on Walmart and sort them by price.
- What does item 18493462688 cost right now, and who holds the buy box?
- Show me every other seller offering this item and what they charge with shipping.
- Read the reviews of this item that mention battery life.
- Pull only the verified-purchase reviews of this item and summarise the complaints.
- Compare the price of this item on walmart.com and walmart.ca.

A prompt that names a product rather than an item id takes two calls, one search to resolve the id and one product lookup to read it. Reviews work the same way, and the search result carries the id both need.

## Tools

Three tools, 10 credits per successful call. Each takes `domain`, either `walmart.com` or `walmart.ca`, and `language`, where `walmart.com` serves `en` and `es` while `walmart.ca` serves `en` and `fr`. A language the storefront does not offer falls back to its default.

Item ids are storefront-scoped. On `walmart.com` they are numeric, such as `18493462688`, and on `walmart.ca` alphanumeric, such as `6NZMJ5CW6MH2`. An id from one storefront does not resolve on the other.

### Get Walmart search results

[`hasdata_walmart_search_getSearchResults`](https://docs.hasdata.com/apis/walmart/search?utm_source=github&utm_medium=syndication&utm_campaign=walmart-mcp)

A page of search results for a keyword, a category, or both.

| Parameter | Type | Required | Notes |
| :--- | :--- | :--- | :--- |
| `q` | string | see below | The search term |
| `catId` | string | see below | Category id from a category URL, such as `976759_1086446_1229651` |
| `url` | string | | A full Walmart search or category URL, scraped as is. Overrides the parameters above |
| `domain` | string | | `walmart.com` or `walmart.ca` |
| `language` | string | | `en`, `es` or `fr`, subject to the storefront |
| `sort` | string | | `bestMatch`, `priceLowToHigh`, `priceHighToLow`, `bestseller`, `highlyRated` or `newArrivals` |
| `page` | number | | Result page, starting at 1 |
| `minPrice` / `maxPrice` | number | | Price band in the storefront currency |
| `deliveryType` | string | | `shipping` or `pickup` |
| `facet` | string | | One filter in `name:value` form, such as `brand:Great Value` |

Send `q` to search, `catId` to browse a whole category, or both to search inside one. Neither appears in the schema's `required` array because either one satisfies the call on its own.

Returns `searchInformation`, a `productResults` array, a `facets` block and `pagination`. Each result carries `position`, `id`, `title`, `url`, `brand`, `isSponsored`, `badges`, `walmartPlusSavings`, `categoryPathId`, a `price` object, `reviews` with `rating` and `totalReviews`, `image`, `seller`, `availability` and `fulfillment`.

The `facets` block is the map of every filter the query supports, and each value carries the exact string to send back in `facet`. Running one unfiltered search to read the facets is cheaper than guessing.

```json
{
  "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 }
}
```

### Get Walmart product details

[`hasdata_walmart_product_getWalmartProduct`](https://docs.hasdata.com/apis/walmart/product?utm_source=github&utm_medium=syndication&utm_campaign=walmart-mcp)

One item in full.

| Parameter | Type | Required | Notes |
| :--- | :--- | :--- | :--- |
| `itemId` | string | see below | The Walmart item id |
| `url` | string | see below | A full product URL, scraped as is. Overrides `itemId` and sets the storefront |
| `domain` | string | | `walmart.com` or `walmart.ca`, ignored when `url` is given |
| `language` | string | | `en`, `es` or `fr`, subject to the storefront |
| `otherOffers` | boolean | | Also collect competing offers. Costs 5 credits on top, 15 instead of 10 |

Pass `itemId` or `url`. As with search, neither is listed as required because either one works alone.

Returns a `product` object with `itemId`, `title`, `url`, `brand`, `brandUrl`, `type`, `model`, `upc`, `condition`, `badges`, `availability`, a `price` object, the `seller` holding the buy box, `reviews`, `images`, `categoryPath`, `categoryPathId`, `highlights`, `specifications`, `keyItemFeatures`, `productDetails` and `fulfillment`.

The base call already reports how many competitors the page advertises and the che