Skip to main content
Glama
mcp-walmart-ads

mcp-walmart-ads

Walmart & Sam's Club APIs

CI PyPI Python 3.13+ License: MIT

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

Platform

APIs

Auth

walmart:ads — Walmart Connect

Sponsored Products, Display

RSA-SHA256 signature + bearer token

walmart:marketplace — Walmart Marketplace

28 domains (orders, items, feeds, reports, …)

OAuth2 client_credentials

samsclub:ads — Sam's Club

Sponsored Products

RSA-SHA256 signature + bearer token

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

Related MCP server: walmart-marketplace-mcp

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"
            }
          }
        }
      }
    }
  }
}

Field

Notes

consumer_id

Partner Network consumer ID

private_key

Path to the RSA private key (PEM). Relative paths resolve against the config directory

private_key_version

Key version string (default "1")

bearer_token

OAuth bearer token

base_urls.<api>

One per api in the platform's discovery surface. Keys MAY be bare (sponsored-products) or fully qualified (walmart:ads:sponsored-products); extra keys are allowed for the auxiliary specs reached by raw method+path

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

Field

Default

Notes

response_cache_ttl

3600

Seconds a truncated body or download stays readable at its resource URI

truncate_threshold

2048

Response bytes returned inline before truncating to a preview

spec_refresh

{"auto": true, "interval": 7}

Background spec refresh. auto turns the sweep on or off; interval is days between sweeps, and MAY be fractional

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.

Parameter

Notes

query

Case-insensitive substring on operation id, path, or summary

api

Limit to one api, e.g. walmart:marketplace:order-management

platform

Limit to one platform — walmart:ads, walmart:marketplace, samsclub:ads (schema enum)

tag

Filter by OpenAPI tag

method

Filter by HTTP verb — GET, POST, PUT, PATCH, DELETE (schema enum)

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.

Parameter

Notes

operation_id

Qualified (api:operationId), or bare when unambiguous

api

Api to resolve a bare id in, e.g. walmart:ads:sponsored-products

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.

Parameter

Notes

region, environment

Required. Src: config

operation_id

Qualified or bare. Resolves api, platform, method, path, and required headers

api

Required with raw method + path; otherwise inferred from operation_id. Accepts the two auxiliary walmart:ads specs

method, path

Raw route, reaching alpha/beta/unpublished endpoints absent from the specs

path_params

Values for {placeholders} in the path

params, body

Query string and JSON body

file_path

Send the file as multipart/form-data — Marketplace feed uploads. Pair with the feedType query parameter

advertiser_id

MUST be given on walmart:marketplace, where it selects the credential. Optional on the ads platforms, where it is sent as X-Advertiser-ID

tenant

WAP tenant for non-US walmart:ads regions

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/<uuid> 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, as a human review gate. The candidate is never shipped and never loaded at runtime.

Documents are stored verbatim as upstream served them, so a refresh diff shows exactly what changed. Oversized inline examples and x-readme metadata are stripped on load rather than on disk, which keeps that reduction retunable without re-downloading anything.

Keeping them current

Specs refresh in the background: once at startup, then every spec_refresh.interval days (7 by default). Set auto to false to stop the sweep — the interval is remembered for whenever you turn it back on, and the manual refresh still works.

To refresh now, having hit an endpoint the bundled spec does not have:

# Installed with uvx (no clone)
uvx mcp-walmart-ads --refresh

# Or from a source checkout
uv run mcp-walmart-ads --refresh

Either form sweeps every spec regardless of the interval and writes the same user cache, printing one row per document: written, unchanged, or error.

There is deliberately no tool for this. A stale spec is indistinguishable from a current one from inside a session — it simply lacks an endpoint — so an agent asked to decide would either never refresh or refresh superstitiously after an unrelated failure. The trigger belongs outside the session.

A document MUST yield at least one operation before it is installed, so an upstream answering 200 with an error body cannot poison the cache, and a byte-identical document is left alone. A cached file that will not load is discarded and the read falls back to the bundle. Servers coordinate through spec-state.json at the cache root, which records when each spec was last tried and holds a lease so one process sweeps at a time — every client session runs its own server process, and without it each would re-download all 33.

Rebuilding the bundle

A maintainer step, and not the same thing as --refresh: that updates your cache, this updates the copies that ship in the wheel.

# Registry-sourced specs only, by default
uv run python scripts/fetch_specs.py
uv run python scripts/fetch_specs.py walmart:ads:sponsored-products walmart:marketplace:order-management

# Regenerate the Sam's Club candidate spec for review
uv run --group spec-build python scripts/build_samsclub_spec.py

MCP resources

Resource URI

Description

wmt://platforms

Every platform, its auth model, and the regions and environments it declares

wmt://platforms/{platform}/apis

That platform's api ids

wmt://platforms/{platform}/apis/{name}

One api: title, version, operation count, and its tags with a count each — the legal list_endpoints(tag=…) values

wmt://platforms/walmart:marketplace/regions/{region}/{environment}/advertisers

Advertiser ids mapped to their Walmart Partner ID (null when unset)

wmt://platforms/{platform}/regions/{region}/{environment}/hosts

Api ids mapped to the base URL a call reaches, or * for every api whose host the server owns

wmt://responses/{request_id}

Full body of a truncated response or a cached download (in memory, TTL from config)

wmt://curl/{request_id}

Reproducible cURL for a previous request, credentials replaced with placeholders

MCP host examples

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "walmart": {
      "command": "uvx",
      "args": ["mcp-walmart-ads"]
    }
  }
}

Add to your Claude Code MCP config:

{
  "mcpServers": {
    "walmart": {
      "command": "uvx",
      "args": ["mcp-walmart-ads"]
    }
  }
}
[mcp_servers.walmart]
command = "uvx"
args = ["mcp-walmart-ads"]
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "walmart": {
      "type": "local",
      "enabled": true,
      "command": ["uvx", "mcp-walmart-ads"]
    }
  }
}
{
  "inputs": [],
  "servers": {
    "walmart": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-walmart-ads"]
    }
  }
}

Development

uv sync --group dev
uv run ruff check src/ tests/ scripts/
uv run ruff format --check src/ tests/ scripts/
uv run pyright
uv run pytest tests/ -v

Contributing

Issues and pull requests are welcome. Keep changes focused; ruff check, ruff format --check, pyright, and pytest MUST all pass.

License

LICENSE.

Available Tools

5 tools
call_endpointA
Destructive

[Walmart] Execute an authenticated API request. Identify the endpoint by operation_id, or by method + path with an api — a raw path also reaches alpha/beta/unpublished endpoints absent from the bundled specs. Auth, signature, market, and correlation headers are added by the server. A body over the configured threshold is truncated to a preview; read the returned cached_at resource for the whole of it.

Inputs: region (required), environment (required), api, body, +8 more. Returns: body, curl, error, cached_at, +2 more

describe_endpointA
Read-only

[Walmart] Describe one OpenAPI operation. Returns it with every components.schemas entry reachable from it, so a request body can be built without the full spec.

Inputs: operation_id (required), api. Returns: object

download_fileA
Idempotent

[Walmart] Download a report, label, or snapshot. Give a full url — such as the details URL from a display snapshot poll, or a Marketplace report url — or an operation_id, or an api with method and path. Written to dest_path when given, otherwise gunzipped and cached. Redirects are followed for you.

Inputs: region (required), environment (required), api, url, +9 more. Returns: path, urls, error, cached_at, +4 more

list_endpointsA
Read-only

[Walmart] List OpenAPI operations across every api. Returned operation ids can be passed straight to describe_endpoint or call_endpoint.

Inputs: api, tag, limit, query, +3 more. Returns: object

refresh_specsA
Idempotent

[Walmart] Refresh OpenAPI specs into the user cache, which then takes precedence over the bundled copies. Omit api to refresh all 33.

Inputs: api. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 5 tools

    Disambiguation4/5

    Each tool has a distinct role: list (enumerate operations), describe (inspect a schema), call (execute JSON requests), download (fetch binary files), refresh (update specs). The only mild overlap is that call_endpoint and download_file both accept operation_id or api+method+path, but their output semantics (JSON response vs. binary file) are clearly separated in the descriptions.

    Naming Consistency5/5

    All five tools follow a clean verb_noun snake_case pattern (list_endpoints, describe_endpoint, call_endpoint, download_file, refresh_specs). The singular/plural difference between describe_endpoint and list_endpoints is a trivial, intuitive deviation.

    Tool Count5/5

    Five tools is a well-scoped set for a meta-API wrapper: discovery, inspection, execution, file retrieval, and cache refresh. Nothing feels redundant or missing at the count level.

    Completeness5/5

    The set covers the full lifecycle of an OpenAPI-driven client: enumerate operations, describe schemas to build bodies, execute authenticated calls, download binary artifacts, and refresh specs including alpha/beta endpoints absent from bundled specs. There are no obvious dead ends for the stated purpose.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that lets you manage a Walmart Marketplace seller account in plain language, including orders, inventory, pricing, returns, WFS fulfillment, and reports.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A MCP server for Walmart Marketplace and Affiliate APIs, enabling sellers to manage items, inventory, prices, and orders, and consumers to search, lookup products, reviews, and store locations.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Amazon Selling Partner API and Advertising API, enabling access to orders, inventory, pricing, ads, and reports via natural language.
      1
      MIT