Walmart Connect Advertising APIs

MCP server for Walmart Connect Ads APIs — Sponsored Search and Display.

Exposes two tools — a generic API proxy (walmart_ads_api) and a display-snapshot downloader (walmart_ads_download_display_snapshot). The AI agent decides which endpoint to call; the server handles RSA-SHA256 signing and auth headers automatically.

Features

• One tool, any endpoint — no code changes needed 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 API reference docs served as MCP resources so the agent knows endpoint schemas

Requirements

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

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

Configuration

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

Windows note: ~ maps to %USERPROFILE% (typically C:\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": 51200,
  "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.pem resolves to ~/.config/mcp-walmart-ads/keys/us/prod.pem.

... View full README on GitHub