Walmart Ads MCP Server

Walmart Connect Advertising APIs

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

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.

Features

• 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

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.

config.example.json also includes a CA region that uses the same API hosts as US. Select the WAP market with the per-call tenant parameter (see below), not via different base URLs.

Market → tenant (wap-tenant-id)

Pass tenant on call_endpoint / download_display_snapshot for non-US WAP markets. Omit for US.

Tools

list_endpoints

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

describe_endpoint

Return one operation plus the components.schemas reachable from it (its $ref closure), so request bodies and responses can be built without the full spec.

call_endpoint

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

* Provide either operation_id, or both method and path.

refresh_specs

Re-fetch the bundled OpenAPI specs from ReadMe's public api-registry into a user cache (~/.cache/mcp-walmart-ads/specs/) that takes precedence over the bundled copy.

download_display_snapshot

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 the details field after polling a display snapshot to done status.

MCP resources

Endpoint schemas come from the bundled OpenAPI specs via list_endpoints / describe_endpoint (see Tools), not from static resources.

Dynamic resources

MCP host examples

Cursor

Add to .cursor/mcp.json:

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

Claude Code

Add to your Claude Code MCP config:

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

Codex

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

OpenCode

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

GitHub Copilot

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

Development

uv sync --group dev    # install deps
uv run pytest          # run tests
uv run ruff check .    # lint
uv run ruff format .   # format
uv run pyright         # type check

Contributing

Open issues or PRs. Follow existing style and add tests where appropriate.

License

MIT. See LICENSE.