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 <line>:<name> 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\<you>), 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>

<platform> 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.