{
  "markdown": "# Walmart Connect Advertising APIs\n\n[![CI](https://github.com/alyiox/mcp-walmart-ads/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/alyiox/mcp-walmart-ads/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/mcp-walmart-ads.svg)](https://pypi.org/project/mcp-walmart-ads/)\n[![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\n<!-- mcp-name: io.github.alyiox/mcp-walmart-ads -->\n\nMCP server for [Walmart Connect Ads APIs](https://developer.walmart.com/advertising-partners) — Sponsored Search and Display.\n\nExposes 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.\n\n## Features\n\n- **Spec-driven discovery** — list/describe endpoints from bundled OpenAPI specs, refreshable at runtime\n- **Any endpoint** — call by operation id or raw method+path (raw path reaches unpublished endpoints); no code changes when APIs evolve\n- Supports both Sponsored Search and Display API families\n- Multi-region, multi-environment (production + staging) via config file\n- Per-request RSA-SHA256 signing with automatic header construction\n- Large responses truncated with full data available via MCP resource URI\n- Bundled OpenAPI specs (refreshable at runtime) give the agent endpoint schemas on demand\n\n## Requirements\n\n- Python 3.13+\n- Walmart Connect Partner Network credentials (consumer ID, RSA key pair, bearer token)\n\n## Quick start\n\nSet up your config (see [Configuration](#configuration)), then run the server:\n\n```bash\n# Run directly with uvx (no clone needed)\nnpx -y @modelcontextprotocol/inspector uvx mcp-walmart-ads\n```\n\n```bash\n# Or run from source\ngit clone https://github.com/alyiox/mcp-walmart-ads.git\ncd mcp-walmart-ads\nuv sync\nnpx -y @modelcontextprotocol/inspector uv run mcp-walmart-ads\n```\n\n## Configuration\n\nThe config file lives under your home directory at `~/.config/mcp-walmart-ads/config.json`.\n\n> **Windows note:** `~` maps to `%USERPROFILE%` (typically `C:\\Users\\<you>`), so the\n> full path is `%USERPROFILE%\\.config\\mcp-walmart-ads\\config.json`.\n\n**1. Create the config directory and copy the example**\n\n```bash\n# Unix-like (macOS, Linux, WSL, …)\nmkdir -p ~/.config/mcp-walmart-ads/keys/us\ncp config.example.json ~/.config/mcp-walmart-ads/config.json\n```\n\n```powershell\n# Windows (PowerShell)\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.config\\mcp-walmart-ads\\keys\\us\"\nCopy-Item config.example.json \"$env:USERPROFILE\\.config\\mcp-walmart-ads\\config.json\"\n```\n\n**2. Edit `~/.config/mcp-walmart-ads/config.json`**\n\n```json\n{\n  \"response_cache_ttl\": 3600,\n  \"truncate_threshold\": 1024,\n  \"regions\": {\n    \"US\": {\n      \"production\": {\n        \"consumer_id\": \"your-consumer-id\",\n        \"private_key\": \"./keys/us/prod.pem\",\n        \"private_key_version\": \"1\",\n        \"bearer_token\": \"your-bearer-token\",\n        \"base_urls\": {\n          \"search\": \"https://developer.api.walmart.com/api-proxy/service/WPA/Api/v1\",\n          \"display\": \"https://developer.api.walmart.com/api-proxy/service/display/api/v1\"\n        }\n      },\n      \"staging\": {\n        \"consumer_id\": \"your-staging-consumer-id\",\n        \"private_key\": \"./keys/us/staging.pem\",\n        \"private_key_version\": \"1\",\n        \"bearer_token\": \"your-staging-bearer-token\",\n        \"base_urls\": {\n          \"search\": \"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1\",\n          \"display\": \"https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1\"\n        }\n      }\n    }\n  }\n}\n```\n\n**3. Place your RSA private key PEM files in `~/.config/mcp-walmart-ads/keys/`**\n\nKey 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`.\n\n`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.\n\n| Config field | Description |\n|---|---|\n| `response_cache_ttl` | Seconds to keep truncated responses in memory (default `3600`) |\n| `truncate_threshold` | Response byte limit before truncation (default `1024`) |\n| `regions.<R>.<E>.consumer_id` | Your Walmart Connect consumer ID |\n| `regions.<R>.<E>.private_key` | Path to RSA private key PEM (relative to config dir or absolute) |\n| `regions.<R>.<E>.private_key_version` | Key version string (default `\"1\"`) |\n| `regions.<R>.<E>.bearer_token` | OAuth bearer token |\n| `regions.<R>.<E>.base_urls.search` | Sponsored Search API base URL |\n| `regions.<R>.<E>.base_urls.display` | Display API base URL |\n\n### Market → tenant (`wap-tenant-id`)\n\nPass `tenant` on `call_endpoint` / `download_display_snapshot` for non-US WAP markets. Omit for US.\n\n| Market | `tenant` value |\n|---|---|\n| US | *(omit)* |\n| CA | `WMT_CA` |\n| MX | `WMT_MX`, `WBD_OD`, or `WMT_BD` |\n\n## Tools\n\n### `list_endpoints`\n\nList operations from the bundled OpenAPI spec for an `ad_type`, with optional filters.\n\n| Parameter | Required | Description |\n|---|---|---|\n| `ad_type` | yes | `search` or `display` |\n| `query` | no | Case-insensitive substring match on operationId, path, or summary |\n| `tag` | no | Filter to operations whose OpenAPI tags include this value |\n| `method` | no | Filter by HTTP verb |\n\n### `describe_endpoint`\n\nReturn one operation plus the `components.schemas` reachable from it (its `$ref` closure), so request bodies and responses can be built without the full spec.\n\n| Parameter | Required | Description |\n|---|---|---|\n| `ad_type` | yes | `search` or `display` |\n| `operation_id` | yes | Spec operation id (from `list_endpoints`) |\n\n### `call_endpoint`\n\nExecute 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.\n\n| Parameter | Required | Description |\n|---|---|---|\n| `region` | yes | e.g. `US` |\n| `env` | yes | `production` or `staging` |\n| `ad_type` | yes | `search` or `display` |\n| `operation_id` | no* | Spec operation id; resolves `method`+`path` |\n| `method` | no* | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` |\n| `path` | no* | e.g. `/api/v1/campaigns` |\n| `params` | no | Query string parameters (JSON object) |\n| `body` | no | JSON request body for POST/PUT (object or array) |\n| `advertiser_id` | no | Sent as `X-Advertiser-ID`; required by many display/creative/campaign endpoints |\n| `tenant` | no | Sent as `wap-tenant-id` for non-US WAP (e.g. `WMT_CA`); omit for US |\n\n\\* Provide either `operation_id`, or both `method` and `path`.\n\n### `refresh_specs`\n\nRe-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.\n\n| Parameter | Required | Description |\n|---|---|---|\n| `spec_id` | no | One spec to refresh (e.g. `search/sponsored-products`); omit to refresh all |\n\n### `download_display_snapshot`\n\nDownload 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.\n\n| Parameter | Required | Description |\n|---|---|---|\n| `region` | yes | e.g. `US` or `CA` |\n| `env` | yes | `production` or `staging` |\n| `download_url` | yes | Full URL from the snapshot poll `details` field |\n| `advertiser_id` | yes | Advertiser ID used when creating the snapshot |\n| `tenant` | no | Sent as `wap-tenant-id` for non-US WAP; omit for US |\n\n## MCP resources\n\nEndpoint schemas come from the bundled OpenAPI specs via `list_endpoints` / `describe_endpoint` (see [Tools](#tools)), not from static resources.\n\n### Dynamic resources\n\n| Resource URI | Description |\n|---|---|\n| `wmc://config` | Available regions, environments, and ad types from your config |\n| `wmc://responses/{request_id}` | Full body of a truncated API response (cached in memory, TTL from config) |\n| `wmc://curl/{request_id}` | Reproducible cURL command for a previous API request |\n\n## MCP host examples\n\n### Cursor\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"walmart-ads\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-walmart-ads\"]\n    }\n  }\n}\n```\n\n### Claude Code\n\nAdd to your Claude Code MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"walmart-ads\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-walmart-ads\"]\n    }\n  }\n}\n```\n\n### Codex\n\n```toml\n[mcp_servers.walmart-ads]\ncommand = \"uvx\"\nargs = [\"mcp-walmart-ads\"]\n```\n\n### OpenCode\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"mcp\": {\n    \"walmart-ads\": {\n      \"type\": \"local\",\n      \"enabled\": true,\n      \"command\": [\"uvx\", \"mcp-walmart-ads\"]\n    }\n  }\n}\n```\n\n### GitHub Copilot\n\n```json\n{\n  \"inputs\": [],\n  \"servers\": {\n    \"walmart-ads\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-walmart-ads\"]\n    }\n  }\n}\n```\n\n## Development\n\n```bash\nuv sync --group dev    # install deps\nuv run pytest          # run tests\nuv run ruff check .    # lint\nuv run ruff format .   # format\nuv run pyright         # type check\n```\n\n## Contributing\n\nOpen issues or PRs. Follow existing style and add tests where appropriate.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 9656,
  "sha": "f069687060a60ea3da79765c289fd245dc2579b8970cf318b03e21a62fc13b69",
  "repo_slug": "alyiox/mcp-walmart-ads",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_alyiox_mcp_walmart_ads_06de422f/readme"
}