hasdata-walmart-mcp 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- hasdata_walmart_mcp-1.0.0/.github/ISSUE_TEMPLATE/inaccuracy.md +21 -0
- hasdata_walmart_mcp-1.0.0/.github/workflows/contract.yml +31 -0
- hasdata_walmart_mcp-1.0.0/.github/workflows/publish.yml +75 -0
- hasdata_walmart_mcp-1.0.0/.gitignore +11 -0
- hasdata_walmart_mcp-1.0.0/LICENSE +21 -0
- hasdata_walmart_mcp-1.0.0/PKG-INFO +468 -0
- hasdata_walmart_mcp-1.0.0/README.md +454 -0
- hasdata_walmart_mcp-1.0.0/glama.json +7 -0
- hasdata_walmart_mcp-1.0.0/hasdata_walmart_mcp/__init__.py +28 -0
- hasdata_walmart_mcp-1.0.0/index.mjs +24 -0
- hasdata_walmart_mcp-1.0.0/package.json +41 -0
- hasdata_walmart_mcp-1.0.0/pyproject.toml +24 -0
- hasdata_walmart_mcp-1.0.0/server.json +61 -0
- hasdata_walmart_mcp-1.0.0/test/tools.test.mjs +186 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: Something in the README is wrong
|
|
3
|
+
about: A tool table, a response sample or a documented behaviour does not match reality
|
|
4
|
+
labels: documentation
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
**Where in the README**
|
|
8
|
+
|
|
9
|
+
Section or heading.
|
|
10
|
+
|
|
11
|
+
**What it says**
|
|
12
|
+
|
|
13
|
+
Quote the line.
|
|
14
|
+
|
|
15
|
+
**The call you made**
|
|
16
|
+
|
|
17
|
+
Tool name and arguments, or the equivalent REST URL with your key removed.
|
|
18
|
+
|
|
19
|
+
**What came back**
|
|
20
|
+
|
|
21
|
+
Trimmed response, with anything private removed.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# The tool contract is checked on a schedule as well as on push, because the upstream tool list
|
|
2
|
+
# can change without a single commit in this repository.
|
|
3
|
+
name: tool contract
|
|
4
|
+
|
|
5
|
+
on:
|
|
6
|
+
push:
|
|
7
|
+
branches: [main]
|
|
8
|
+
pull_request:
|
|
9
|
+
schedule:
|
|
10
|
+
- cron: '0 6 * * 1'
|
|
11
|
+
workflow_dispatch:
|
|
12
|
+
|
|
13
|
+
permissions:
|
|
14
|
+
contents: read
|
|
15
|
+
|
|
16
|
+
jobs:
|
|
17
|
+
contract:
|
|
18
|
+
runs-on: ubuntu-latest
|
|
19
|
+
timeout-minutes: 5
|
|
20
|
+
steps:
|
|
21
|
+
- uses: actions/checkout@v4
|
|
22
|
+
- uses: actions/setup-node@v4
|
|
23
|
+
with:
|
|
24
|
+
node-version: '22'
|
|
25
|
+
# Forks cannot read repository secrets. The suite skips its live checks when the key is
|
|
26
|
+
# absent, so a pull request from a fork stays green instead of failing for a reason the
|
|
27
|
+
# contributor cannot fix.
|
|
28
|
+
- name: Assert the tool list still matches the README
|
|
29
|
+
env:
|
|
30
|
+
HASDATA_API_KEY: ${{ secrets.HASDATA_API_KEY }}
|
|
31
|
+
run: npm test
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# Publishes the npm and PyPI wrapper packages on a version tag, using OIDC
|
|
2
|
+
# trusted publishing. No NPM_TOKEN or PYPI_TOKEN is stored anywhere: GitHub
|
|
3
|
+
# mints a short-lived OIDC token per run, and npmjs.org / pypi.org accept it
|
|
4
|
+
# because this repo + workflow are configured as trusted publishers.
|
|
5
|
+
#
|
|
6
|
+
# One-time setup, done once per package on the registries (not in this repo):
|
|
7
|
+
# npmjs.org -> package settings -> Trusted Publisher -> GitHub Actions,
|
|
8
|
+
# repo HasData/walmart-mcp, workflow publish.yml
|
|
9
|
+
# pypi.org -> the hasdata org -> Publishing -> add a trusted publisher
|
|
10
|
+
# (pending publisher works before the first release),
|
|
11
|
+
# repo HasData/walmart-mcp, workflow publish.yml
|
|
12
|
+
#
|
|
13
|
+
# The MCP registry entry (com.hasdata/walmart) is NOT published here. It uses
|
|
14
|
+
# domain auth, which would need the namespace-wide Ed25519 key as a secret in
|
|
15
|
+
# every repo. That key stays off CI; the registry entry is published by hand
|
|
16
|
+
# when server.json changes, after the package versions below are live.
|
|
17
|
+
#
|
|
18
|
+
# Release: bump nothing by hand. Tag the commit `vX.Y.Z` and push the tag; the
|
|
19
|
+
# tag is the single source of the version and is written into both manifests.
|
|
20
|
+
|
|
21
|
+
name: publish
|
|
22
|
+
|
|
23
|
+
on:
|
|
24
|
+
push:
|
|
25
|
+
tags: ['v*.*.*']
|
|
26
|
+
|
|
27
|
+
permissions:
|
|
28
|
+
contents: read
|
|
29
|
+
id-token: write
|
|
30
|
+
|
|
31
|
+
jobs:
|
|
32
|
+
npm:
|
|
33
|
+
runs-on: ubuntu-latest
|
|
34
|
+
steps:
|
|
35
|
+
- uses: actions/checkout@v4
|
|
36
|
+
# No registry-url here on purpose. With it, setup-node writes an .npmrc
|
|
37
|
+
# carrying _authToken=${NODE_AUTH_TOKEN}, which resolves to a placeholder
|
|
38
|
+
# when no token is passed. npm then authenticates with that garbage instead
|
|
39
|
+
# of falling back to OIDC, and a scoped package answers 404.
|
|
40
|
+
- uses: actions/setup-node@v4
|
|
41
|
+
with:
|
|
42
|
+
node-version: '24'
|
|
43
|
+
# OIDC trusted publishing landed in npm 11.5.1. Node 24 already ships a
|
|
44
|
+
# newer npm than that, but pinning the upgrade here keeps the job working
|
|
45
|
+
# if the runner image drifts back.
|
|
46
|
+
- name: Upgrade npm for OIDC trusted publishing
|
|
47
|
+
run: |
|
|
48
|
+
npm install -g npm@latest
|
|
49
|
+
npm -v
|
|
50
|
+
- name: Set version from the tag
|
|
51
|
+
run: npm version "${GITHUB_REF_NAME#v}" --no-git-tag-version --allow-same-version
|
|
52
|
+
- name: Publish to npm (OIDC, no token)
|
|
53
|
+
run: npm publish --access public
|
|
54
|
+
|
|
55
|
+
pypi:
|
|
56
|
+
runs-on: ubuntu-latest
|
|
57
|
+
steps:
|
|
58
|
+
- uses: actions/checkout@v4
|
|
59
|
+
- uses: actions/setup-python@v5
|
|
60
|
+
with:
|
|
61
|
+
python-version: '3.12'
|
|
62
|
+
- name: Set version from the tag
|
|
63
|
+
run: |
|
|
64
|
+
python - "${GITHUB_REF_NAME#v}" <<'PY'
|
|
65
|
+
import re, sys
|
|
66
|
+
v = sys.argv[1]
|
|
67
|
+
p = "pyproject.toml"
|
|
68
|
+
t = open(p, encoding="utf-8").read()
|
|
69
|
+
t = re.sub(r'(?m)^version = ".*"$', f'version = "{v}"', t, count=1)
|
|
70
|
+
open(p, "w", encoding="utf-8", newline="\n").write(t)
|
|
71
|
+
PY
|
|
72
|
+
- name: Build the wheel and sdist
|
|
73
|
+
run: pipx run build
|
|
74
|
+
- name: Publish to PyPI (OIDC, no token)
|
|
75
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 HasData
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,468 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: hasdata-walmart-mcp
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: MCP server for Walmart through HasData's hosted API. 1,000 free credits every month.
|
|
5
|
+
Project-URL: Homepage, https://docs.hasdata.com/apis/walmart/search
|
|
6
|
+
Project-URL: Repository, https://github.com/HasData/walmart-mcp
|
|
7
|
+
License: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Keywords: ecommerce,hasdata,mcp,model-context-protocol,price-monitoring,product-data,walmart
|
|
10
|
+
Requires-Python: >=3.10
|
|
11
|
+
Requires-Dist: mcp-proxy>=0.12.0
|
|
12
|
+
Requires-Dist: mcp<2,>=1.17
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
|
|
15
|
+
# Walmart MCP Server
|
|
16
|
+
|
|
17
|
+
<!-- mcp-name: com.hasdata/walmart -->
|
|
18
|
+
|
|
19
|
+
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.
|
|
20
|
+
|
|
21
|
+
It reads public Walmart pages that a signed-out visitor can see, on `walmart.com` and `walmart.ca`.
|
|
22
|
+
|
|
23
|
+
**1,000 free credits every month, no card required**, which is 100 Walmart calls at the 10-credit rate.
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
https://mcp.hasdata.com/api/mcp?apis=walmart
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
[](https://glama.ai/mcp/servers/HasData/walmart-mcp)
|
|
30
|
+
[](https://github.com/HasData/walmart-mcp/actions/workflows/contract.yml)
|
|
31
|
+
[](https://mcp.hasdata.com/api/mcp?apis=walmart)
|
|
32
|
+
[](#tools)
|
|
33
|
+
[](https://www.npmjs.com/package/@hasdata/walmart-mcp)
|
|
34
|
+
[](https://pypi.org/project/hasdata-walmart-mcp/)
|
|
35
|
+
[](LICENSE)
|
|
36
|
+
|
|
37
|
+
## Contents
|
|
38
|
+
|
|
39
|
+
- [What you need](#what-you-need)
|
|
40
|
+
- [Quick start](#quick-start)
|
|
41
|
+
- [Example prompts](#example-prompts)
|
|
42
|
+
- [Tools](#tools)
|
|
43
|
+
- [Errors and failure paths](#errors-and-failure-paths)
|
|
44
|
+
- [Pricing, free tier and limits](#pricing-free-tier-and-limits)
|
|
45
|
+
- [Tool selection](#tool-selection)
|
|
46
|
+
- [How it compares](#how-it-compares)
|
|
47
|
+
- [FAQ](#faq)
|
|
48
|
+
- [HasData links](#hasdata-links)
|
|
49
|
+
- [Development](#development)
|
|
50
|
+
- [Contributing](#contributing)
|
|
51
|
+
- [License](#license)
|
|
52
|
+
|
|
53
|
+
## What you need
|
|
54
|
+
|
|
55
|
+
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.
|
|
56
|
+
|
|
57
|
+
## Quick start
|
|
58
|
+
|
|
59
|
+
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.
|
|
60
|
+
|
|
61
|
+
| Field | Value |
|
|
62
|
+
| :--- | :--- |
|
|
63
|
+
| URL | `https://mcp.hasdata.com/api/mcp?apis=walmart` |
|
|
64
|
+
| Transport | HTTP, streamable |
|
|
65
|
+
| Auth header | `x-api-key: HASDATA_API_KEY` |
|
|
66
|
+
|
|
67
|
+
Clients with OAuth support can add the same URL as a connector and sign in without putting a key in a config file.
|
|
68
|
+
|
|
69
|
+
<details>
|
|
70
|
+
<summary><b>Claude Code</b></summary>
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
claude mcp add --transport http walmart "https://mcp.hasdata.com/api/mcp?apis=walmart" \
|
|
74
|
+
--header "x-api-key: HASDATA_API_KEY"
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
</details>
|
|
78
|
+
|
|
79
|
+
<details>
|
|
80
|
+
<summary><b>Claude Desktop</b></summary>
|
|
81
|
+
|
|
82
|
+
Settings, then Connectors, then Add custom connector, then paste `https://mcp.hasdata.com/api/mcp?apis=walmart` and sign in.
|
|
83
|
+
|
|
84
|
+
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`:
|
|
85
|
+
|
|
86
|
+
```json
|
|
87
|
+
{
|
|
88
|
+
"mcpServers": {
|
|
89
|
+
"walmart": {
|
|
90
|
+
"command": "npx",
|
|
91
|
+
"args": ["-y", "@hasdata/walmart-mcp"],
|
|
92
|
+
"env": { "HASDATA_API_KEY": "YOUR_KEY" }
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
For Python instead of Node, swap the launcher for the PyPI package, which `uvx` runs without a manual install:
|
|
99
|
+
|
|
100
|
+
```json
|
|
101
|
+
{
|
|
102
|
+
"mcpServers": {
|
|
103
|
+
"walmart": {
|
|
104
|
+
"command": "uvx",
|
|
105
|
+
"args": ["hasdata-walmart-mcp"],
|
|
106
|
+
"env": { "HASDATA_API_KEY": "YOUR_KEY" }
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
</details>
|
|
113
|
+
|
|
114
|
+
<details>
|
|
115
|
+
<summary><b>Cursor</b></summary>
|
|
116
|
+
|
|
117
|
+
`~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one:
|
|
118
|
+
|
|
119
|
+
```json
|
|
120
|
+
{
|
|
121
|
+
"mcpServers": {
|
|
122
|
+
"walmart": {
|
|
123
|
+
"url": "https://mcp.hasdata.com/api/mcp?apis=walmart",
|
|
124
|
+
"headers": { "x-api-key": "HASDATA_API_KEY" }
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
</details>
|
|
131
|
+
|
|
132
|
+
<details>
|
|
133
|
+
<summary><b>Windsurf</b></summary>
|
|
134
|
+
|
|
135
|
+
`~/.codeium/windsurf/mcp_config.json`. Windsurf calls the field `serverUrl`, not `url`:
|
|
136
|
+
|
|
137
|
+
```json
|
|
138
|
+
{
|
|
139
|
+
"mcpServers": {
|
|
140
|
+
"walmart": {
|
|
141
|
+
"serverUrl": "https://mcp.hasdata.com/api/mcp?apis=walmart",
|
|
142
|
+
"headers": { "x-api-key": "HASDATA_API_KEY" }
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
</details>
|
|
149
|
+
|
|
150
|
+
<details>
|
|
151
|
+
<summary><b>VS Code</b></summary>
|
|
152
|
+
|
|
153
|
+
`.vscode/mcp.json` in the workspace:
|
|
154
|
+
|
|
155
|
+
```json
|
|
156
|
+
{
|
|
157
|
+
"servers": {
|
|
158
|
+
"walmart": {
|
|
159
|
+
"type": "http",
|
|
160
|
+
"url": "https://mcp.hasdata.com/api/mcp?apis=walmart",
|
|
161
|
+
"headers": { "x-api-key": "HASDATA_API_KEY" }
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
</details>
|
|
168
|
+
|
|
169
|
+
## Example prompts
|
|
170
|
+
|
|
171
|
+
Each of these lands on one tool, or on two in sequence when the second needs the item id the first returns.
|
|
172
|
+
|
|
173
|
+
- Find laptop stands under $30 on Walmart and sort them by price.
|
|
174
|
+
- What does item 18493462688 cost right now, and who holds the buy box?
|
|
175
|
+
- Show me every other seller offering this item and what they charge with shipping.
|
|
176
|
+
- Read the reviews of this item that mention battery life.
|
|
177
|
+
- Pull only the verified-purchase reviews of this item and summarise the complaints.
|
|
178
|
+
- Compare the price of this item on walmart.com and walmart.ca.
|
|
179
|
+
|
|
180
|
+
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.
|
|
181
|
+
|
|
182
|
+
## Tools
|
|
183
|
+
|
|
184
|
+
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.
|
|
185
|
+
|
|
186
|
+
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.
|
|
187
|
+
|
|
188
|
+
### Get Walmart search results
|
|
189
|
+
|
|
190
|
+
[`hasdata_walmart_search_getSearchResults`](https://docs.hasdata.com/apis/walmart/search?utm_source=github&utm_medium=syndication&utm_campaign=walmart-mcp)
|
|
191
|
+
|
|
192
|
+
A page of search results for a keyword, a category, or both.
|
|
193
|
+
|
|
194
|
+
| Parameter | Type | Required | Notes |
|
|
195
|
+
| :--- | :--- | :--- | :--- |
|
|
196
|
+
| `q` | string | see below | The search term |
|
|
197
|
+
| `catId` | string | see below | Category id from a category URL, such as `976759_1086446_1229651` |
|
|
198
|
+
| `url` | string | | A full Walmart search or category URL, scraped as is. Overrides the parameters above |
|
|
199
|
+
| `domain` | string | | `walmart.com` or `walmart.ca` |
|
|
200
|
+
| `language` | string | | `en`, `es` or `fr`, subject to the storefront |
|
|
201
|
+
| `sort` | string | | `bestMatch`, `priceLowToHigh`, `priceHighToLow`, `bestseller`, `highlyRated` or `newArrivals` |
|
|
202
|
+
| `page` | number | | Result page, starting at 1 |
|
|
203
|
+
| `minPrice` / `maxPrice` | number | | Price band in the storefront currency |
|
|
204
|
+
| `deliveryType` | string | | `shipping` or `pickup` |
|
|
205
|
+
| `facet` | string | | One filter in `name:value` form, such as `brand:Great Value` |
|
|
206
|
+
|
|
207
|
+
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.
|
|
208
|
+
|
|
209
|
+
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`.
|
|
210
|
+
|
|
211
|
+
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.
|
|
212
|
+
|
|
213
|
+
```json
|
|
214
|
+
{
|
|
215
|
+
"position": 1,
|
|
216
|
+
"id": "18493462688",
|
|
217
|
+
"title": "Incipio Portable Foldable Aluminum Laptop Stand and Riser with Adjustable Angles, Anti-Slip and Ventilated Design",
|
|
218
|
+
"url": "https://www.walmart.com/ip/Portable-Laptop-Stand-Black/18493462688",
|
|
219
|
+
"isSponsored": true,
|
|
220
|
+
"badges": ["Overall pick"],
|
|
221
|
+
"walmartPlusSavings": true,
|
|
222
|
+
"categoryPathId": "4125_4134_1074326_9623037_7875081",
|
|
223
|
+
"price": { "currentPrice": 9.96, "currentPriceDisplay": "$9.96" },
|
|
224
|
+
"reviews": { "rating": 4.5, "totalReviews": 49 }
|
|
225
|
+
}
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
### Get Walmart product details
|
|
229
|
+
|
|
230
|
+
[`hasdata_walmart_product_getWalmartProduct`](https://docs.hasdata.com/apis/walmart/product?utm_source=github&utm_medium=syndication&utm_campaign=walmart-mcp)
|
|
231
|
+
|
|
232
|
+
One item in full.
|
|
233
|
+
|
|
234
|
+
| Parameter | Type | Required | Notes |
|
|
235
|
+
| :--- | :--- | :--- | :--- |
|
|
236
|
+
| `itemId` | string | see below | The Walmart item id |
|
|
237
|
+
| `url` | string | see below | A full product URL, scraped as is. Overrides `itemId` and sets the storefront |
|
|
238
|
+
| `domain` | string | | `walmart.com` or `walmart.ca`, ignored when `url` is given |
|
|
239
|
+
| `language` | string | | `en`, `es` or `fr`, subject to the storefront |
|
|
240
|
+
| `otherOffers` | boolean | | Also collect competing offers. Costs 5 credits on top, 15 instead of 10 |
|
|
241
|
+
|
|
242
|
+
Pass `itemId` or `url`. As with search, neither is listed as required because either one works alone.
|
|
243
|
+
|
|
244
|
+
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`.
|
|
245
|
+
|
|
246
|
+
The base call already reports how many competitors the page advertises and the cheapest competing price. Turn on `otherOffers` only when you need the offers themselves, because it takes a second request to Walmart and costs half again as much.
|
|
247
|
+
|
|
248
|
+
```json
|
|
249
|
+
{
|
|
250
|
+
"itemId": "18493462688",
|
|
251
|
+
"brand": "Incipio",
|
|
252
|
+
"condition": "New",
|
|
253
|
+
"price": { "currentPrice": 9.96, "currentPriceDisplay": "$9.96", "currency": "USD" },
|
|
254
|
+
"seller": {
|
|
255
|
+
"name": "Walmart.com",
|
|
256
|
+
"id": "F55CDC31AB754BB68FE0B39041159D63",
|
|
257
|
+
"returnPolicy": "Free 30-day returns"
|
|
258
|
+
},
|
|
259
|
+
"reviews": {
|
|
260
|
+
"totalReviews": 49,
|
|
261
|
+
"rating": 4.5,
|
|
262
|
+
"fiveStars": 38,
|
|
263
|
+
"fourStars": 4,
|
|
264
|
+
"threeStars": 3,
|
|
265
|
+
"twoStars": 1,
|
|
266
|
+
"oneStar": 3
|
|
267
|
+
},
|
|
268
|
+
"specifications": [{ "name": "Maximum screen size", "value": "16 in" }],
|
|
269
|
+
"fulfillment": {
|
|
270
|
+
"type": "FC",
|
|
271
|
+
"message": "Pickup, today at Fredericksburg Massaponax Supercenter",
|
|
272
|
+
"deliveryDate": "2026-09-09T21:59:00.000Z"
|
|
273
|
+
}
|
|
274
|
+
}
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
### Get Walmart product reviews
|
|
278
|
+
|
|
279
|
+
[`hasdata_walmart_reviews_getWalmartReviews`](https://docs.hasdata.com/apis/walmart/reviews?utm_source=github&utm_medium=syndication&utm_campaign=walmart-mcp)
|
|
280
|
+
|
|
281
|
+
The review feed of one item, ten reviews a page.
|
|
282
|
+
|
|
283
|
+
| Parameter | Type | Required | Notes |
|
|
284
|
+
| :--- | :--- | :--- | :--- |
|
|
285
|
+
| `itemId` | string | see below | The Walmart item id |
|
|
286
|
+
| `url` | string | see below | A full product URL whose reviews to read. Overrides `itemId` |
|
|
287
|
+
| `domain` | string | | `walmart.com` or `walmart.ca`, ignored when `url` is given |
|
|
288
|
+
| `language` | string | | Language of the review page, not of the reviews themselves |
|
|
289
|
+
| `page` | number | | Review page, ten a page |
|
|
290
|
+
| `sort` | string | | `mostRelevant`, `mostRecent`, `mostHelpful`, `highestRated`, `lowestRated` or `oldest` |
|
|
291
|
+
| `rating` | number | | Keep one star rating, 1 to 5 |
|
|
292
|
+
| `aspectId` | string | | Keep reviews mentioning one topic, by its id |
|
|
293
|
+
| `condition` | string | | Keep reviews about one condition of the item |
|
|
294
|
+
| `verifiedPurchasesOnly` | boolean | | Keep only purchases Walmart confirmed |
|
|
295
|
+
|
|
296
|
+
Returns `reviewsInformation`, a `reviewResults` array, a `filters` block, `appliedFilters` and `pagination`.
|
|
297
|
+
|
|
298
|
+
`filters` is the part worth reading first. It lists the star ratings, frequent mentions and conditions this item can actually be filtered by, each with a count and with the exact `value` to send back. Given `{"name": "Battery Life", "value": "6049", "count": 8}` you send `aspectId: "6049"` and expect eight reviews. Guessing an aspect id instead of reading it here is the usual way to get an empty page.
|
|
299
|
+
|
|
300
|
+
`reviewsInformation` carries the item rating, the per-star breakdown, per-aspect scores and Walmart's AI review summary. It also separates `totalRatings` from `totalReviews`, which matter separately: the item below has 49 ratings but only 21 written reviews, and paging covers the 21.
|
|
301
|
+
|
|
302
|
+
```json
|
|
303
|
+
{
|
|
304
|
+
"reviewsInformation": {
|
|
305
|
+
"rating": 4.49,
|
|
306
|
+
"totalRatings": 49,
|
|
307
|
+
"totalReviews": 21,
|
|
308
|
+
"recommendedPercentage": 100,
|
|
309
|
+
"ratingBreakdown": { "fiveStars": 38, "fourStars": 4, "threeStars": 3, "twoStars": 1, "oneStar": 3 }
|
|
310
|
+
},
|
|
311
|
+
"reviewResults": [
|
|
312
|
+
{
|
|
313
|
+
"position": 1,
|
|
314
|
+
"id": "434698083",
|
|
315
|
+
"rating": 5,
|
|
316
|
+
"title": "Good value laptop stand.",
|
|
317
|
+
"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.",
|
|
318
|
+
"date": "8/1/2026",
|
|
319
|
+
"verifiedPurchase": true,
|
|
320
|
+
"helpfulVotes": 0,
|
|
321
|
+
"notHelpfulVotes": 0,
|
|
322
|
+
"badges": ["Verified Purchase"],
|
|
323
|
+
"seller": "Walmart.com",
|
|
324
|
+
"language": "English",
|
|
325
|
+
"aspects": [{ "id": "284", "polarity": "Positive" }]
|
|
326
|
+
}
|
|
327
|
+
],
|
|
328
|
+
"filters": [
|
|
329
|
+
{ "name": "Star rating", "parameter": "rating", "values": [{ "name": "5 stars", "value": "5", "count": 38 }] },
|
|
330
|
+
{ "name": "Frequent mentions", "parameter": "aspectId", "values": [{ "name": "Sturdiness", "value": "828", "count": 6 }] }
|
|
331
|
+
],
|
|
332
|
+
"pagination": { "currentPage": 1, "reviewsPerPage": 10, "totalPages": 3, "totalResults": 21, "nextPage": 2 }
|
|
333
|
+
}
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
## Errors and failure paths
|
|
337
|
+
|
|
338
|
+
Plan for these rather than assuming a happy path.
|
|
339
|
+
|
|
340
|
+
**Two totals disagree in one search response, and both are correct.** `searchInformation.totalResultsDisplay` is the string Walmart prints on the page, such as `"1000+"`, while `pagination.totalResults` is the number behind it, such as `8005`. One is display text and the other is an integer, so do not parse the first or print the second.
|
|
341
|
+
|
|
342
|
+
**Walmart stops serving results after roughly page 10.** Beyond that the page comes back empty rather than erroring. A large keyword cannot be enumerated by paging, so narrow it with `facet`, a price band or a category instead.
|
|
343
|
+
|
|
344
|
+
**Prices belong to one store, and the response says which.** `searchInformation.storeId` names it, and `fulfillment.message` names it in words, down to `"Pickup, today at Fredericksburg Massaponax Supercenter"`. Comparing prices across calls only means something while that store stays the same.
|
|
345
|
+
|
|
346
|
+
**`deliveryType: pickup` is answered against a single store.** An item in stock nationally can still come back unavailable, because it is unavailable at that one store rather than everywhere.
|
|
347
|
+
|
|
348
|
+
**The product tool reports ratings where you might read reviews.** Its `reviews.totalReviews` is the count of ratings, 49 for the item above, while the reviews tool reports 49 ratings and 21 written reviews separately. Use the reviews tool when the distinction matters.
|
|
349
|
+
|
|
350
|
+
**Review dates are `M/D/YYYY` strings.** `"8/1/2026"` is the first of August, not the eighth of January. Parse with the format in hand rather than letting a date library guess.
|
|
351
|
+
|
|
352
|
+
**A review can carry an aspect id absent from `filters`.** The block lists the topics the item can be filtered by, which is a shorter list than the topics its reviews were tagged with. Read aspects off the review, and filter only with ids the block offers.
|
|
353
|
+
|
|
354
|
+
**`variants` is missing rather than empty on an item with no variants.** Check for the key before you read it.
|
|
355
|
+
|
|
356
|
+
**Only one `condition` per request.** The parameter takes a single value, so a query across two conditions is two calls.
|
|
357
|
+
|
|
358
|
+
Results that carry data also carry a `requestMetadata.id` worth quoting in support.
|
|
359
|
+
|
|
360
|
+
## Pricing, free tier and limits
|
|
361
|
+
|
|
362
|
+
Each Walmart tool costs **10 credits per successful call**. Turning on `otherOffers` adds 5 credits to the product call, 15 instead of 10, so leave it off unless the competing offers are the point. Response size does not change the price.
|
|
363
|
+
|
|
364
|
+
The free tier is **1,000 credits every month with no card**, which is 100 Walmart calls at the base rate. It renews with the billing cycle, so a low-volume agent runs on the free tier indefinitely.
|
|
365
|
+
|
|
366
|
+
Paid plans start at **$49 a month** for 200,000 credits, which is 20,000 calls. The unit price falls with volume, from **$2.45 per 1,000 calls** on the entry plan to **$1.00** on Business, **$0.84** on Growth and **$0.74** on the largest [high-volume plans](https://hasdata.com/prices?utm_source=github&utm_medium=syndication&utm_campaign=walmart-mcp).
|
|
367
|
+
|
|
368
|
+
Your plan also sets concurrency. The free tier allows 1 request at a time, Startup 15, Business 30, Growth 50, and the high-volume plans run from 200 to 1,500. Retry on the 429 with a backoff in anything unattended, because an agent that fans out across item ids will reach the ceiling before you do.
|
|
369
|
+
|
|
370
|
+
A request that comes back non-200 is not billed. A successful call that finds nothing is still a call.
|
|
371
|
+
|
|
372
|
+
## Tool selection
|
|
373
|
+
|
|
374
|
+
Start from what the prompt gives you. A keyword or a category goes to the search tool, an item id goes straight to the product or reviews tool. Spending a search call to reach an id you already have is the most common waste.
|
|
375
|
+
|
|
376
|
+
Then pick by what the question is about. The search result is enough for ranking, price sweeps and share-of-shelf work across many items. The product tool is the only one carrying specifications, the buy-box seller and the competing-offer count. The reviews tool is the only one carrying review text.
|
|
377
|
+
|
|
378
|
+
Read the `filters` block before you filter. One unfiltered reviews call tells you which ratings, topics and conditions exist and how many reviews each holds, which turns a guessed filter into a known one.
|
|
379
|
+
|
|
380
|
+
## How it compares
|
|
381
|
+
|
|
382
|
+
Walmart's own Affiliate and Marketplace APIs are the official routes to this data, and they answer different questions.
|
|
383
|
+
|
|
384
|
+
| | Walmart Affiliate API | Walmart Marketplace API | This server |
|
|
385
|
+
| :--- | :--- | :--- | :--- |
|
|
386
|
+
| Eligibility | An approved affiliate account | A Walmart seller account | An API key |
|
|
387
|
+
| Scope | Items in the affiliate catalogue | Your own listings and orders | Any public item page |
|
|
388
|
+
| Competing sellers | Not returned | Your own offers only | The offer list, with `otherOffers` |
|
|
389
|
+
| Review text | Not returned | Reviews of your items | The feed, with filters |
|
|
390
|
+
| Buy box | Not returned | For your items | Whoever holds it |
|
|
391
|
+
| `walmart.ca` | Separate programme | Separate account | A parameter |
|
|
392
|
+
| Cost | Free, when you qualify | Free with a seller account | Paid past the free tier |
|
|
393
|
+
|
|
394
|
+
The row that decides it is scope. Both official APIs answer questions about a catalogue you have a commercial relationship with, which rules them out for watching a competitor. When the items are yours, the Marketplace API is authoritative and free, and you should use it.
|
|
395
|
+
|
|
396
|
+
## FAQ
|
|
397
|
+
|
|
398
|
+
### Is there an official Walmart MCP server?
|
|
399
|
+
|
|
400
|
+
Walmart does not publish one. This one is maintained by HasData and reads public Walmart pages.
|
|
401
|
+
|
|
402
|
+
### What is a Walmart MCP server?
|
|
403
|
+
|
|
404
|
+
An MCP server exposes tools an AI client can call. This one turns Walmart search results, item pages and review feeds into JSON an agent can reason over, without a browser or a scraping library in your stack.
|
|
405
|
+
|
|
406
|
+
### Do I need a Walmart account or a seller account?
|
|
407
|
+
|
|
408
|
+
No. The only credential is your HasData key.
|
|
409
|
+
|
|
410
|
+
### Which storefronts are covered?
|
|
411
|
+
|
|
412
|
+
`walmart.com` and `walmart.ca`. They hold separate catalogues, item ids, prices and currencies, so a cross-storefront comparison is a real comparison rather than a currency conversion.
|
|
413
|
+
|
|
414
|
+
### Why did my item id return nothing?
|
|
415
|
+
|
|
416
|
+
Most often because it belongs to the other storefront. A numeric id is `walmart.com` and an alphanumeric one is `walmart.ca`, and neither resolves on the other. Pass `domain` to match, or pass the full `url` and let it set the storefront.
|
|
417
|
+
|
|
418
|
+
### How do I get the competing offers?
|
|
419
|
+
|
|
420
|
+
Set `otherOffers` on the product call. Each offer comes back with the seller name, storefront URL, price, condition, shipping cost, delivery date and return policy. It costs 5 credits more, because it takes a second request to Walmart.
|
|
421
|
+
|
|
422
|
+
### Why does the same search return different prices on different days?
|
|
423
|
+
|
|
424
|
+
Partly because prices move, and partly because the response is answered against one Walmart store, reported as `searchInformation.storeId`. Hold that store constant before reading a price change as a price change.
|
|
425
|
+
|
|
426
|
+
### Can I use this together with other HasData APIs?
|
|
427
|
+
|
|
428
|
+
Yes. One key covers everything, and one endpoint serves them all through the `apis` parameter. Point a client at `?apis=walmart,amazon` to get both tool sets in one connection, or at [`mcp.hasdata.com/api/mcp`](https://docs.hasdata.com/mcp-server?utm_source=github&utm_medium=syndication&utm_campaign=walmart-mcp) for the full catalogue.
|
|
429
|
+
|
|
430
|
+
### Is HasData affiliated with Walmart?
|
|
431
|
+
|
|
432
|
+
No. HasData is an independent service and is not affiliated with, endorsed by, or sponsored by Walmart. Walmart is a trademark of its respective owner. The tools work with publicly available data only, and you are responsible for using the results in line with Walmart's terms and the law that applies to you.
|
|
433
|
+
|
|
434
|
+
### Compliance and personal data
|
|
435
|
+
|
|
436
|
+
Reviews carry an author name as the reviewer chose to publish it, along with a verified-purchase flag. Marketplace seller entries carry a business name and a storefront URL. Neither block needs the author fields for sentiment or pricing work, so drop them unless your purpose needs them, and check your own obligations before storing them.
|
|
437
|
+
|
|
438
|
+
## HasData links
|
|
439
|
+
|
|
440
|
+
- [Walmart API documentation](https://docs.hasdata.com/apis/walmart/search?utm_source=github&utm_medium=syndication&utm_campaign=walmart-mcp), the REST endpoints behind these tools
|
|
441
|
+
- [MCP server documentation](https://docs.hasdata.com/mcp-server?utm_source=github&utm_medium=syndication&utm_campaign=walmart-mcp)
|
|
442
|
+
- [Pricing](https://hasdata.com/prices?utm_source=github&utm_medium=syndication&utm_campaign=walmart-mcp)
|
|
443
|
+
- [Dashboard](https://app.hasdata.com/sign-up?utm_source=github&utm_medium=syndication&utm_campaign=walmart-mcp)
|
|
444
|
+
|
|
445
|
+
Other HasData MCP servers: [Google Search](https://github.com/HasData/google-search-mcp), [Google Maps](https://github.com/HasData/google-maps-mcp), [Google Trends](https://github.com/HasData/google-trends-mcp), [Google Flights](https://github.com/HasData/google-flights-mcp), [DuckDuckGo](https://github.com/HasData/duckduckgo-mcp), [YouTube](https://github.com/HasData/youtube-mcp), [TikTok](https://github.com/HasData/tiktok-mcp), [Instagram](https://github.com/HasData/instagram-mcp), [Amazon](https://github.com/HasData/amazon-mcp), [Shopify](https://github.com/HasData/shopify-mcp), [Yelp](https://github.com/HasData/yelp-mcp), [Zillow](https://github.com/HasData/zillow-mcp), [Redfin](https://github.com/HasData/redfin-mcp), [Airbnb](https://github.com/HasData/airbnb-mcp), [Booking.com](https://github.com/HasData/booking-mcp), [Indeed](https://github.com/HasData/indeed-mcp).
|
|
446
|
+
|
|
447
|
+
## Development
|
|
448
|
+
|
|
449
|
+
The launcher is a thin stdio bridge to the remote server, so there is nothing to build.
|
|
450
|
+
|
|
451
|
+
```bash
|
|
452
|
+
npm install
|
|
453
|
+
HASDATA_API_KEY=your_key_here npm test
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
The tests in `test/` assert the tool contract, the part that can break without a commit here. They check that `?apis=walmart` returns the expected tool count, that no name changed, that every tool still carries a description, that the either/or parameters this README documents are still in the schema, and that the key in use is actually accepted. That last check calls a tool for real and costs 10 credits, which is the price of a canary that can fail for the right reason.
|
|
457
|
+
|
|
458
|
+
None of the three tools declares a required parameter, because each accepts one of two inputs. The suite pins the alternatives instead of the `required` array, which would pass while the schema said nothing.
|
|
459
|
+
|
|
460
|
+
The contract suite also runs weekly on a schedule, because the upstream tool list can change without anyone touching this repository.
|
|
461
|
+
|
|
462
|
+
## Contributing
|
|
463
|
+
|
|
464
|
+
A tool table, a response sample or a documented behaviour that does not match reality is worth an issue. There is a template for exactly that. Pull requests are welcome for the same, and for anything in the launcher.
|
|
465
|
+
|
|
466
|
+
## License
|
|
467
|
+
|
|
468
|
+
MIT, see [LICENSE](LICENSE).
|