HasData Walmart README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the HasData Walmart listing page.
Walmart MCP Server
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.
Contents
- What you need
- Quick start
- Example prompts
- Tools
- Errors and failure paths
- Pricing, free tier and limits
- Tool selection
- How it compares
- FAQ
- HasData links
- Development
- Contributing
- License
What you need
An MCP client and a HasData API key from the dashboard, 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/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.
Claude Code
Claude Desktop
Settings, then Connectors, then Add custom connector, then paste https://mcp.hasdata.com/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:
For Python instead of Node, swap the launcher for the PyPI package, which uvx runs without a manual install:
Cursor
~/.cursor/mcp.json for every project, or .cursor/mcp.json for one:
Windsurf
~/.codeium/windsurf/mcp_config.json. Windsurf calls the field serverUrl, not url:
VS Code
.vscode/mcp.json in the workspace:
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
| Tool | What it returns |
|---|---|
hasdata_walmart_product_getWalmartProduct | Title, brand, model, UPC, condition, availability, price with strikethrough before-price and unit price, the seller holding the buy box with its rating and return…. 10 credits a call |
hasdata_walmart_reviews_getWalmartReviews | Each review with its rating, title, full text with paragraphs preserved, submission date, author, verified-purchase flag, helpful and not-helpful vote counts, badges,…. 10 credits a call |
hasdata_walmart_search_getSearchResults | The product list with item id, title, product URL, brand, price and strikethrough before-price, star rating, review count, seller, availability, sponsored flag, badges,…. 10 credits a call |
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
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.
Get Walmart product details
hasdata_walmart_product_getWalmartProduct
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 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.
Get Walmart product reviews
hasdata_walmart_reviews_getWalmartReviews
The review feed of one item, ten reviews a page.
| Parameter | Type | Required | Notes |
|---|---|---|---|
itemId | string | see below | The Walmart item id |
url | string | see below | A full product URL whose reviews to read. Overrides itemId |
domain | string | walmart.com or walmart.ca, ignored when url is given | |
language | string | Language of the review page, not of the reviews themselves | |
page | number | Review page, ten a page | |
sort | string | mostRelevant, mostRecent, mostHelpful, highestRated, lowestRated or oldest | |
rating | number | Keep one star rating, 1 to 5 | |
aspectId | string | Keep reviews mentioning one topic, by its id | |
condition | string | Keep reviews about one condition of the item | |
verifiedPurchasesOnly | boolean | Keep only purchases Walmart confirmed |
Returns reviewsInformation, a reviewResults array, a filters block, appliedFilters and pagination.
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.
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.
Errors and failure paths
Plan for these rather than assuming a happy path.
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.
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.
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.
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.
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.
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.
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.
variants is missing rather than empty on an item with no variants. Check for the key before you read it.
Only one condition per request. The parameter takes a single value, so a query across two conditions is two calls.
Results that carry data also carry a requestMetadata.id worth quoting in support.
Pricing, free tier and limits
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.
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.
Paid plans start at $59 a month for 200,000 credits, which is 20,000 calls. The unit price falls with volume, from $2.95 per 1,000 calls on the entry plan to $1.19 on Basic and $0.83 across the Growth tiers. Current figures live on the pricing page.
Your plan also sets concurrency. The free tier allows 1 request at a time, Startup 5, Basic 15, and the Growth tiers run from 50 to 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.
A request that comes back non-200 is not billed. A successful call that finds nothing is still a call.
Tool selection
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.
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.
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.
How it compares
Walmart's own Affiliate and Marketplace APIs are the official routes to this data, and they answer different questions.
| Walmart Affiliate API | Walmart Marketplace API | This server | |
|---|---|---|---|
| Eligibility | An approved affiliate account | A Walmart seller account | An API key |
| Scope | Items in the affiliate catalogue | Your own listings and orders | Any public item page |
| Competing sellers | Not returned | Your own offers only | The offer list, with otherOffers |
| Review text | Not returned | Reviews of your items | The feed, with filters |
| Buy box | Not returned | For your items | Whoever holds it |
walmart.ca | Separate programme | Separate account | A parameter |
| Cost | Free, when you qualify | Free with a seller account | Paid past the free tier |
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.
FAQ
Is there an official Walmart MCP server?
Walmart does not publish one. This one is maintained by HasData and reads public Walmart pages.
What is a Walmart MCP server?
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.
Do I need a Walmart account or a seller account?
No. The only credential is your HasData key.
Which storefronts are covered?
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.
Why did my item id return nothing?
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.
How do I get the competing offers?
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.
Why does the same search return different prices on different days?
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.
Can I use this together with other HasData APIs?
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 for the full catalogue.
Is HasData affiliated with Walmart?
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.
Compliance and personal data
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.
HasData links
- Walmart API documentation, the REST endpoints behind these tools
- MCP server documentation
- Pricing
- Dashboard
Other HasData MCP servers: Google Search, Google Maps, Google Trends, Google Flights, DuckDuckGo, YouTube, TikTok, Instagram, Amazon, Shopify, Yelp, Zillow, Redfin, Airbnb, Booking.com, Indeed.
Development
The launcher is a thin stdio bridge to the remote server, so there is nothing to build.
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.
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.
The contract suite also runs weekly on a schedule, because the upstream tool list can change without anyone touching this repository.
Contributing
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.
License
MIT, see LICENSE.