Walmart Marketplace

CI PyPI Python 3.13+ License: MIT

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

Config field	Description
response_cache_ttl	Seconds to keep truncated responses in memory (default 3600)
truncate_threshold	Response byte limit before truncation (default 1024)
regions.<R>	Region label — case-insensitive, free-form. Groups advertisers; it does not change which host is called
regions.<R>.<E>	Environment — exactly production or sandbox
…<E>.credentials[]	One entry per Walmart client credential
…credentials[].client_id	Walmart client ID (UUID)
…credentials[].client_secret	Walmart client secret, as plain text
…credentials[].advertisers	Sellers this credential serves, each {"id": …} with an optional "partner_id"

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

Tool	Purpose
list_endpoints	List operations across the bundled specs, filtered by query, domain, tag, or method
describe_endpoint	One operation plus its schema closure, with server-managed headers stripped
call_endpoint	Execute any operation by id or raw method+path
upload_feed	Upload a feed file (multipart) for a feed type
download_file	Download a report, label, or other binary to a local path
refresh_specs	Re-pull specs from the ReadMe api-registry into the user cache

Resources

URI	Contents
wmm://config	Configured regions, environments, and advertiser ids
wmm://responses/{request_id}	Full body of a truncated response
wmm://curl/{request_id}	Equivalent cURL command for a previous request

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