Walmart & Sam's Club APIs

Walmart & Sam's Club APIs

MCP server for three Walmart Inc. API families, behind one tool surface:

Four tools over 31 apis and 424 operations — discovery, a generic proxy, and a downloader. An agent finds endpoints in the bundled OpenAPI specs and calls them; the server signs, acquires tokens, and builds headers.

walmart:ads:sponsored-products:SBAProfileUpdateV2

└─ retailer ─┘└ line ┘└─── api name ───┘└── operationId ──┘ └────────── platform ─────────┘ credentials attach here

An operation id alone resolves to a host and an auth model. A matching : suffix means the same surface for another retailer — 13 shared operation ids of 90.

Requirements

• Python 3.13+
• Credentials for whichever platforms you use. Configure only those — an absent platform is simply unconfigured, and discovery works with no credentials at all.
• Walmart Connect / Sam's Club — consumer ID, RSA key pair, bearer token
• Walmart Marketplace — client ID + secret, and the advertiser (seller profile) ids they serve

Quick start

Set up your config (see Configuration), then run the server:

# Run directly with uvx (no clone needed)

npx -y @modelcontextprotocol/inspector@latest uvx mcp-walmart-ads

# Or run from source

git clone https://github.com/alyiox/mcp-walmart-ads.git cd mcp-walmart-ads uv sync npx -y @modelcontextprotocol/inspector@latest uv run mcp-walmart-ads

Configuration

config.json MUST live at ~/.config/mcp-walmart-ads/config.json. The server reads it once at startup, so a corrected file REQUIRES a restart.

Windows: ~ maps to %USERPROFILE% (typically C:\Users\ ), making the full

path %USERPROFILE%\.config\mcp-walmart-ads\config.json.

Create the directory and copy the example:

# Unix-like (macOS, Linux, WSL, …)

mkdir -p ~/.config/mcp-walmart-ads/keys/walmart-ads cp config.example.json ~/.config/mcp-walmart-ads/config.json

# Windows (PowerShell)

New-Item -ItemType Directory -Force "$env:USERPROFILE\.config\mcp-walmart-ads\keys\walmart-ads" Copy-Item config.example.json "$env:USERPROFILE\.config\mcp-walmart-ads\config.json"

Shape

platforms.<platform>.regions.<region>.<environment> = <auth block>

is the two-segment prefix an api id starts with, so a config key is literally the value you pass as the platform tool parameter — nothing to translate.

The auth block's shape follows the platform's auth model. There is exactly one shape per platform, so no discriminator field is needed.

Signature platforms (walmart:ads, samsclub:ads):

{

"platforms": { "walmart:ads": { "regions": { "us": { "production": { "consumer_id": "your-consumer-id", "private_key": "./keys/walmart-ads/us-prod.pem", "private_key_version": "1", "bearer_token": "your-bearer-token", "base_urls": { "sponsored-products": "https://developer.api.walmart.com/api-proxy/service/WPA/Api/v1", "display": "https://developer.api.walmart.com/api-proxy/service/display/api/v1" } } } } } } }

Environment names are free-form here — Walmart may issue a tenant only production, or production and staging.

OAuth2 platform (walmart:marketplace):

{

"platforms": { "walmart:marketplace": { "regions": { "us": { "production": { "credentials": [ { "client_id": "your-client-id", "client_secret": "your-client-secret", "advertisers": [ { "id": 7060158, "partner_id": "10001234" }, { "id": 7060159 } ] } ] } } } } } }

environment MUST be production or sandbox; base URLs are fixed by the server and absent from the file. Advertiser ids nest under the credential that serves them, so a secret appears exactly once and a dangling advertiser reference is structurally impossible. partner_id is per-seller because two payments operations require it as WM_PARTNER_ID; an all-zero value reads as absent, since that is what a generated config writes for a seller without one, and scripts/backfill_partner_ids.py fills the gaps from Walmart.

Regions are a namespace, not a route — every walmart:marketplace region reaches the same hosts. The level exists because advertiser ids are unique only within a region.

Splitting the config

A populated walmart:marketplace block runs to tens of kilobytes of credentials, 88% of the file here, and a stray comma while editing it takes down every platform: a parse failure precedes per-platform validation. Platforms MAY therefore live in drop-in files under config.d/, merged over the base:

~/.config/mcp-walmart-ads/

├── config.json # server-wide settings, and any platforms you like ├── config.d/ │ ├── walmart-marketplace.json # only a "platforms" object │ └── samsclub-ads.json └── keys/

• A drop-in MUST declare only platforms; server-wide settings stay in config.json.
• A platform declared in two files is an error naming both — never silent precedence.
• Only *.json directly in config.d/ is read, so .bak and editor swap files are ignored.
• A file that fails to parse costs only its own platforms; the rest keep working.
• Relative private_key paths resolve against config.json's directory either way, so moving a platform into config.d/ needs no path edits.
• No config.d/ directory means no change in behavior.

A malformed block for one platform MUST NOT stop the others loading. Read wmt://platforms to see which loaded and what regions and environments they declare: one that failed has no regions, and reading one of its environments returns the loader's own message — which file, which fields, and that a fix needs a restart.

Top-level options

Market → tenant (wap-tenant-id)

Pass tenant on call_endpoint and download_file for non-US walmart:ads markets (WMT_CA, WMT_MX, WBD_OD, …). Omit it for US and for walmart:marketplace.

Tools

list_endpoints

List operations across every api, with optional filters.

Returned operation ids are qualified (api:operationId) and pass straight to describe_endpoint or call_endpoint.

describe_endpoint

One operation plus every components.schemas entry reachable from it, so a request body can be built without the full spec. Server-managed auth and QoS headers are omitted.

call_endpoint

Execute an authenticated request against any configured platform. Signing, token acquisition with per-credential caching and single-flight refresh, and one retry after a 401 all happen server-side.

A response larger than truncate_threshold is previewed inline, with the full body at wmt://responses/{request_id} and a reproducible cURL at wmt://curl/{request_id} — bearer tokens, access tokens, and signatures replaced with placeholders.

download_file

Download a report, label, or snapshot from an authenticated endpoint. Give a full url (the details URL from a display snapshot poll, say), or operation_id, or api with method + path. platform is required only for a bare url.

With dest_path the bytes are written there. Without it they are gunzipped when gzipped and cached, and the result carries cached_at — a binary payload with no dest_path asks for one instead. Redirects are followed, keeping auth headers on a relative or same-host Location and dropping credentials cross-host; the result includes urls, the hop path.

Specs

33 OpenAPI documents ship in the wheel. A refresh writes updated copies to ~/.cache/mcp-walmart-ads/specs/, which outranks the bundle on read. The bundle is never written at runtime, so it stays the floor a damaged or missing cache falls back to.

Where they come from

Walmart publishes no OpenAPI files, but each ReadMe reference page hydrates its HTML with the registry UUIDs of its documents, and https://dash.readme.com/api/v1/api-registry/ serves the full spec unauthenticated. That covers Walmart Connect and all 28 Marketplace domains. Sam's Club publishes neither, so its spec is hand-authored from the developer docs: scripts/build_samsclub_spec.py regenerates a *candidate* from those docs, and the scheduled spec drift workflow opens a PR when they change,