Walmart Marketplace APIs

MCP server for Walmart Marketplace APIs — items, orders, inventory, prices, promotions, feeds, reports, returns, fulfillment, and more.

Exposes spec-driven discovery (`list_endpoints`, `describe_endpoint`), a generic API proxy (`call_endpoint`), feed upload and file download helpers, and a runtime spec refresher (`refresh_specs`). The AI agent discovers endpoints from bundled OpenAPI specs then calls them; the server handles OAuth2 token acquisition, refresh, and Walmart's required headers automatically. Base addresses are hardcoded per environment, so the config file carries nothing but credentials.

Features

• Spec-driven discovery — 28 bundled OpenAPI specs covering 234 operations, refreshable at runtime
• Any endpoint — call by operation id or raw method+path; no code changes when APIs evolve
• Automatic OAuth2 — tokens fetched, cached per credential, refreshed before expiry, retried once on 401. The client secret never leaves token acquisition
• Multi-advertiser — many seller credentials per region and environment, selected per call
• Multi-region, multi-environment — production and sandbox
• Required Walmart headers (`WM_SEC.ACCESS_TOKEN`, `WM_SVC.NAME`, `WM_QOS.CORRELATION_ID`, `WM_MARKET`, `WM_GLOBAL_VERSION`, `WM_SANDBOX`, `WM_PARTNER_ID`) injected server-side and hidden from the agent
• Large responses truncated with full data available via MCP resource URI

Requirements

• Python 3.13+
• Walmart Marketplace client ID and client secret per seller (Developer Portal)

Quick start

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

# Run directly with uvx (no clone needed)
npx -y @modelcontextprotocol/inspector uvx mcp-walmart-marketplace

# Or run from source
git clone https://github.com/alyiox/mcp-walmart-marketplace.git
cd mcp-walmart-marketplace
uv sync
npx -y @modelcontextprotocol/inspector uv run mcp-walmart-marketplace

Configuration

The config file lives under your home directory at `~/.config/mcp-walmart-marketplace/config.json`.

> Windows note: `~` maps to `%USERPROFILE%`, so the full path is

> `%USERPROFILE%\.config\mcp-walmart-marketplace\config.json`.

1. Create the config directory and copy the example

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

2. Edit `~/.config/mcp-walmart-marketplace/config.json`

{
  "response_cache_ttl": 3600,
  "truncate_threshold": 1024,
  "regions": {
    "primary": {
      "production": {
        "credentials": [
          {
            "client_id": "11111111-2222-3333-4444-555555555555",
            "client_secret": "acme-client-secret-goes-here",
            "advertisers": [
              { "id": 1000001, "partner_id": "10000000001" },
              { "id": 1000002 }
            ]
          }
        ]
      },
      "sandbox": {
        "credentials": [
          {
            "client_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
            "client_secret": "acme-sandbox-client-secret-goes-here",
            "advertisers": [{ "id": 1000001 }]
          }
        ]
      }
    }
  }
}

Keep the config file readable only by you — it holds client secrets in plain text.

Everything else is fixed by the server: base URLs (`marketplace.walmartapis.com` for production, `sandbox.walmartapis.com` for sandbox), `WM_SVC.NAME`, the `client_credentials` grant, and the per-operation `WM_MARKET` / `WM_SANDBOX` header values.

Regions

A region is a namespace, not a route. Base addresses are fixed by the server per environment, so every region reaches the same Walmart hosts. The level exists so advertiser ids only have to be unique within one region — the same id under two regions can mean different sellers with different credentials.

Partner IDs

Add `partner_id` to a seller that has a Walmart Partner ID:

"advertisers": [
  { "id": 1000001, "partner_id": "10000000001" },
  { "id": 1000002 }
]

Two `payments` operations — `payments:getTaxForms` and `payments:downloadTaxForm` — require it as the `WM_PARTNER_ID` header. Calling one for a seller configured without a partner id fails with a message telling you to add it, rather than a Walmart 400. Every other operation ignores it, so most entries are just `{"id": …}`.

Advertisers

`advertiser_id` is required on every tool that reaches the network; there is no default. Read the `wmm://config` resource to discover which advertiser ids are configured. It reports region, environment, and advertiser ids only — never client ids or secrets.

Tools

Resources

MCP host examples

Cursor

Add to `.cursor/mcp.json`:

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

Claude Code

Add to your Claude Code MCP config:

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

Codex

[mcp_servers.walmart-marketplace]
command = "uvx"
args = ["mcp-walmart-marketplace"]

OpenCode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "walmart-marketplace": {
      "type": "local",
      "enabled": true,
      "command": ["uvx", "mcp-walmart-marketplace"]
    }
  }
}

GitHub Copilot

{
  "inputs": [],
  "servers": {
    "walmart-marketplace": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-walmart-marketplace"]
    }
  }
}

Specs

The 28 bundled specs come from the ReadMe api-registry that backs

`developer.walmart.com`. They load from the user cache dir first

(`~/.cache/mcp-walmart-marketplace/specs/`) and fall back to the copy shipped in

the wheel, so `refresh_specs` takes effect immediately without a reinstall.

The files on disk are stored verbatim as the registry served them, so the

bundle is the source of truth and a refresh diff shows exactly what Walmart

changed. Reduction happens on load, which keeps it a runtime policy rather than

something baked into the files:

• Oversized examples are dropped. There are 3,514 inline `example` payloads

totalling 4.13 MB, but the median is 16 bytes and two `/v3/items/taxonomy`

payloads account for 3.25 MB. Everything at or under `MAX_EXAMPLE_BYTES`

(1 KB) survives — 97% of them, for ~133 KB — so format hints for dates, skus,

and identifiers stay available while the monsters never reach an agent.

• `x-readme` is removed — docs-platform rendering metadata, not API detail.

Cost of loading all 28 specs is ~80 ms once per process; results are cached per

spec and invalidated by file mtime, so a `refresh_specs` takes effect

immediately. `describe_endpoint` output is 5.1 KB at the median and 88 KB at the

worst (six `order-management` operations inline very large response schemas).

To rebuild the bundled copies:

uv run python scripts/fetch_specs.py            # all
uv run python scripts/fetch_specs.py order-management

Caveats

The specs and the API disagree about authentication. 76 operations declare a Basic `Authorization` header built from the client id and secret, and `fulfillment-management` and `insights-management` appear to require it *instead of* an access token. Probed against production, that is wrong: Basic alone returns 401, the access token alone returns 200, on every service tested. This server therefore sends `WM_SEC.ACCESS_TOKEN` on every request and never sends the client secret anywhere except `/v3/token`. If you diff its behavior against the reference docs, that gap is deliberate.

`WM_SVC.NAME` cannot be read from the specs. 103 operations declare the literal placeholder string `"Walmart Service Name"` and only 100 the real value, so it is fixed at `Walmart Marketplace`, which live calls confirm.

Not every documented endpoint is reachable with seller credentials. `GET /v3/utilities/apiStatus` returns HTTP 520 `Unable to route request`, naming `wm_svc.name: PARTNERMANAGEMENTSERVICES` and `wm_svc.env: prod` as the expected headers — but sending exactly those still returns 520. It appears to belong to a service that 3P credentials cannot reach, and the error message is a red herring. Expect a handful of similar cases across 234 operations.

Report endpoints negotiate content strictly. They reject `Accept: */*` with a 406 listing what they can produce, so `Accept` is derived from the media types the operation declares for its success responses (preferring `application/json` when offered). If you add an endpoint whose spec declares no response content, it falls back to `*/*` and may 406.

Live coverage is thin. Seven operations across five domains have returned 200 against production — `feed-management`, `advertising`, `fulfillment-management`, `insights-management`, `settings-management` — including two report downloads that arrive as real Excel workbooks. The other ~227 are wired from the specs and have never been called. Discovery and request construction are covered by tests; upstream behavior is not.

Two known upstream failures, neither a client bug: `fulfillment-management:getInventoryHealthReport` answers 520 `WFS_INTERNAL_SERVER_ERROR`, and `feed-management:getFeedErrorReport` answers 404 for a feed that processed cleanly.

Sandbox is unverified. Walmart issues sandbox credentials separately from production, and nothing here has run against `sandbox.walmartapis.com`. The `WM_SANDBOX: v2` handling — which opts into the *dynamic* sandbox and changes response semantics rather than just routing — is implemented from the specs, not observed.

`upload_feed` is untested end to end. It is exercised by unit tests against a scripted transport only — the sole way to verify it live is to submit a real feed, which mutates a live catalog. `download_file` *has* been verified against production.

The cross-host redirect path is unexercised. `download_file` sheds credentials when a redirect leaves Walmart's host, which matters if a report is ever served from signed storage. Every download observed so far returned its bytes directly, in one hop, so that branch has only unit-test coverage.

License

MIT