Walmart APIs
MCP server for Walmart Connect Ads, Sam's Club Sponsored Ads, and Walmart Marketplace APIs
Open source Open in the app JSON README (API)
About
MCP server for Walmart Connect Ads, Sam's Club Sponsored Ads, and Walmart Marketplace APIs
Details
- Kind
- MCP servers
- Topic
- Marketing & analytics
- Publisher
- alyiox
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.1a6
- Stars
- 1
- Last push
- 2026-08-18T09:31:22Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:02:24
- Updated
- 2026-09-10 02:03:45
- Origin id
io.github.alyiox/mcp-walmart-ads
README
# Walmart Connect Advertising APIs
[](https://github.com/alyiox/mcp-walmart-ads/actions/workflows/ci.yml)
[](https://pypi.org/project/mcp-walmart-ads/)
[](https://www.python.org/downloads/)
[](LICENSE)
<!-- mcp-name: io.github.alyiox/mcp-walmart-ads -->
MCP server for [Walmart Connect Ads APIs](https://developer.walmart.com/advertising-partners) — 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](#configuration)), then run the server:
```bash
# Run directly with uvx (no clone needed)
npx -y @modelcontextprotocol/inspector uvx mcp-walmart-ads
```
```bash
# 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**
```bash
# Unix-like (macOS, Linux, WSL, …)
mkdir -p ~/.config/mcp-walmart-ads/keys/us
cp config.example.json ~/.config/mcp-walmart-ads/config.json
```
```powershell
# 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`**
```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.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.
| 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>.<E>.consumer_id` | Your Walmart Connect consumer ID |
| `regions.<R>.<E>.private_key` | Path to RSA private key PEM (relative to config dir or absolute) |
| `regions.<R>.<E>.private_key_version` | Key version string (default `"1"`) |
| `regions.<R>.<E>.bearer_token` | OAuth bearer token |
| `regions.<R>.<E>.base_urls.search` | Sponsored Search API base URL |
| `regions.<R>.<E>.base_urls.display` | Display API base URL |
### Market → tenant (`wap-tenant-id`)
Pass `tenant` on `call_endpoint` / `download_display_snapshot` for non-US WAP markets. Omit for US.
| Market | `tenant` value |
|---|---|
| US | *(omit)* |
| CA | `WMT_CA` |
| MX | `WMT_MX`, `WBD_OD`, or `WMT_BD` |
## Tools
### `list_endpoints`
List operations from the bundled OpenAPI spec for an `ad_type`, with optional filters.
| Parameter | Required | Description |
|---|---|---|
| `ad_type` | yes | `search` or `display` |
| `query` | no | Case-insensitive substring match on operationId, path, or summary |
| `tag` | no | Filter to operations whose OpenAPI tags include this value |
| `method` | no | Filter by HTTP verb |
### `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.
| Parameter | Required | Description |
|---|---|---|
| `ad_type` | yes | `search` or `display` |
| `operation_id` | yes | Spec operation id (from `list_endpoints`) |
### `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.
| Parameter | Required | Description |
|---|---|---|
| `region` | yes | e.g. `US` |
| `env` | yes | `production` or `staging` |
| `ad_type` | yes | `search` or `display` |
| `operation_id` | no* | Spec operation id; resolves `method`+`path` |
| `method` | no* | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` |
| `path` | no* | e.g. `/api/v1/campaigns` |
| `params` | no | Query string parameters (JSON object) |
| `body` | no | JSON request body for POST/PUT (object or array) |
| `advertiser_id` | no | Sent as `X-Advertiser-ID`; required by many display/creative/campaign endpoints |
| `tenant` | no | Sent as `wap-tenant-id` for non-US WAP (e.g. `WMT_CA`); omit for US |
\* 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.
| Parameter | Required | Description |
|---|---|---|
| `spec_id` | no | One spec to refresh (e.g. `search/sponsored-products`); omit to refresh all |
### `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.
| Parameter | Required | Description |
|---|---|---|
| `region` | yes | e.g. `US` or `CA` |
| `env` | yes | `production` or `staging` |
| `download_url` | yes | Full URL from the snapshot poll `details` field |
| `advertiser_id` | yes | Advertiser ID used when creating the snapshot |
| `tenant` | no | Sent as `wap-tenant-id` for non-US WAP; omit for US |
## MCP resources
Endpoint schemas come from the bundled OpenAPI specs via `list_endpoints` / `describe_endpoint` (see [Tools](#tools)), not from static resources.
### Dynamic resources
| Resource URI | Description |
|---|---|
| `wmc://config` | Available regions, environments, and ad types from your config |
| `wmc://responses/{request_id}` | Full body of a truncated API response (cached in memory, TTL from config) |
| `wmc://curl/{request_id}` | Reproducible cURL command for a previous API request |
## MCP host examples
### Cursor
Add to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"walmart-ads": {
"command": "uvx",
"args": ["mcp-walmart-ads"]
}
}
}
```
### Claude Code
Add to your Claude Code MCP config:
```json
{
"mcpServers": {
"walmart-ads": {
"command": "uvx",
"args": ["mcp-walmart-ads"]
}
}
}
```
### Codex
```toml
[mcp_servers.walmart-ads]
command = "uvx"
args = ["mcp-walmart-ads"]
```
### OpenCode
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"walmart-ads": {
"type": "local",
"enabled": true,
"command": ["uvx", "mcp-walmart-ads"]
}
}
}
```
### GitHub Copilot
```json
{
"inputs": [],
"servers": {
"walmart-ads": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-walmart-ads"]
}
}
}
```
## Development
```bash
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](LICENSE).