mcp-walmart-ads

Exposes spec-driven discovery (list_endpoints,describe_endpoint), a generic API proxy (call_endpoint), a runtime spec refresher (refresh_specs), and a display-snapshot downloader (download_display_snapshot). The AI agent discovers endpoints from bundled OpenAPI specs then calls them; the server handles RSA-SHA256 signing and auth headers automatically.

- Spec-driven discovery— list/describe endpoints from bundled OpenAPI specs, refreshable at runtime
- Any endpoint— call by operation id or raw method+path (raw path reaches unpublished endpoints); no code changes when APIs evolve
- Supports both Sponsored Search and Display API families
- Multi-region, multi-environment (production + staging) via config file
- Per-request RSA-SHA256 signing with automatic header construction
- Large responses truncated with full data available via MCP resource URI
- Bundled OpenAPI specs (refreshable at runtime) give the agent endpoint schemas on demand

- Python 3.13+
- Walmart Connect Partner Network credentials (consumer ID, RSA key pair, bearer token)

# Run directly with uvx (no clone needed) npx -y @modelcontextprotocol/inspector 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 uv run mcp-walmart-ads

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

Windows note:~maps to%USERPROFILE%(typicallyC:\Users\<you>), so the full path is%USERPROFILE%\.config\mcp-walmart-ads\config.json.

1. Create the config directory and copy the example

# Unix-like (macOS, Linux, WSL, …) mkdir -p ~/.config/mcp-walmart-ads/keys/us cp config.example.json ~/.config/mcp-walmart-ads/config.json

# Windows (PowerShell) New-Item -ItemType Directory -Force "$env:USERPROFILE\.config\mcp-walmart-ads\keys\us" Copy-Item config.example.json "$env:USERPROFILE\.config\mcp-walmart-ads\config.json"

2. Edit~/.config/mcp-walmart-ads/config.json

{ "response_cache_ttl": 3600, "truncate_threshold": 1024, "regions": { "US": { "production": { "consumer_id": "your-consumer-id", "private_key": "./keys/us/prod.pem", "private_key_version": "1", "bearer_token": "your-bearer-token", "base_urls": { "search": "https://developer.api.walmart.com/api-proxy/service/WPA/Api/v1", "display": "https://developer.api.walmart.com/api-proxy/service/display/api/v1" } }, "staging": { "consumer_id": "your-staging-consumer-id", "private_key": "./keys/us/staging.pem", "private_key_version": "1", "bearer_token": "your-staging-bearer-token", "base_urls": { "search": "https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1", "display": "https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1" } } } } }

3. Place your RSA private key PEM files in~/.config/mcp-walmart-ads/keys/

Key paths in the config are resolved relative to the config directory, so./keys/us/prod.pemresolves to~/.config/mcp-walmart-ads/keys/us/prod.pem.

config.example.jsonalso includes aCAregion that uses the same API hosts asUS. Select the WAP market with the per-calltenantparameter (see below), not via different base URLs.

Passtenantoncall_endpoint/download_display_snapshotfor non-US WAP markets. Omit for US.

List operations from the bundled OpenAPI spec for anad_type, with optional filters.

Return one operation plus thecomponents.schemasreachable from it (its$refclosure), so request bodies and responses can be built without the full spec.

Execute any Walmart Connect Ads API endpoint. Identify it byoperation_id, or by rawmethod+path. Raw method+path also reaches alpha/beta/unpublished endpoints that are not in the bundled specs. The server handles RSA-SHA256 signing.

• Provide eitheroperation_id, or bothmethodandpath.

Download a display snapshot file (report or entity). Display snapshot URLs require authenticated requests, so this tool handles the signing automatically. Use the full download URL from thedetailsfield after polling a display snapshot todonestatus.