mcp-walmart-ads

# Walmart APIs

[![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)
[![PyPI](https://img.shields.io/pypi/v/mcp-walmart-ads.svg)](https://pypi.org/project/mcp-walmart-ads/)
[![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

<!-- mcp-name: io.github.alyiox/mcp-walmart-ads -->

MCP server for three Walmart Inc. API families, behind one tool surface:

| Platform | APIs | Auth |
|---|---|---|
| `walmart:ads` — [Walmart Connect](https://developer.walmart.com/advertising-partners) | Sponsored Products, Display | RSA-SHA256 signature + bearer token |
| `walmart:marketplace` — [Walmart Marketplace](https://developer.walmart.com/home/us-mp) | 28 domains (orders, items, feeds, reports, …) | OAuth2 `client_credentials` |
| `samsclub:ads` — [Sam's Club](https://developer.samsclub.com) | Sponsored Products | RSA-SHA256 signature + bearer token |

Five tools over 31 apis and 424 operations:

```
walmart:ads:sponsored-products:SBAProfileUpdateV2
└─ retailer ─┘└ line ┘└─── api name ───┘└── operationId ──┘
   └────────── platform ─────────┘  credentials attach here
```

Spec-driven discovery (`list_endpoints`,
`describe_endpoint`), a generic API proxy (`call_endpoint`), a downloader
(`download_file`), and a runtime spec refresher (`refresh_specs`). The agent discovers
endpoints from bundled OpenAPI specs and calls them; the server handles signing, token
acquisition, and header construction.

## Features

- **Hierarchical api ids** — `<retailer>:<line>:<name>`, e.g.
  `walmart:ads:sponsored-products`, `walmart:marketplace:order-management`,
  `samsclub:ads:sponsored-products`. An operation id appends `:operationId`. Credentials
  attach at the two-segment prefix, so an operation id alone resolves to a host and an
  auth model without the caller naming either
- **Mirrored surfaces are reported** — Sam's Club mirrors Walmart Connect's
  sponsored-products API, so `wmt://apis` and `describe_endpoint` carry `mirrored_by`
  and an agent can move what it knows from one retailer to the other
- **Spec-driven discovery** — list/describe endpoints from 33 bundled OpenAPI specs,
  refreshable at runtime; `describe_endpoint` returns an operation plus its full
  `components.schemas` closure and strips the headers the server owns
- **Any endpoint** — call by operation id or raw method+path; raw paths reach
  alpha/beta/unpublished endpoints absent from the specs
- **Both auth models** — per-request RSA-SHA256 signing for the ads platforms; OAuth2
  token acquisition with per-credential caching, single-flight refresh, and one retry
  after a 401 for Marketplace
- **Per-platform config isolation** — a malformed block for one platform does not stop
  the others loading, and discovery works with no credentials at all
- **Credential-safe cURL** — every cached cURL replaces bearer tokens, access tokens,
  and signatures with placeholders
- Large responses truncated, with the full body available at an MCP resource URI

## Requirements

- Python 3.13+
- Credentials for whichever platforms you use:
  - **Walmart Connect / Sam's Club** — consumer ID, RSA key pair, bearer token
  - **Walmart Marketplace** — client ID + secret, and the advertiser (seller profile) ids they serve

## 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/walmart-ads
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\walmart-ads"
Copy-Item config.example.json "$env:USERPROFILE\.config\mcp-walmart-ads\config.json"
```

**2. Fill in your credentials.** Configure only the platforms you use — an absent
platform is simply unconfigured, and the discovery tools keep working regardless.

### Shape

```
platforms.<platform>.regions.<region>.<environment> = <auth block>
```

`<platform>` is the two-segment prefix an api id starts with, so a config key is literally
the value you pass as the `platform` tool parameter — nothing to translate.

The auth block's shape follows the platform's auth model. There is exactly one shape per
platform, so no discriminator field is needed.

**Signature platforms** (`walmart:ads`, `samsclub:ads`):

```json
{
  "platforms": {
    "walmart:ads": {
      "regions": {
        "us": {
          "production": {
            "consumer_id": "your-consumer-id",
            "private_key": "./keys/walmart-ads/us-prod.pem",
            "private_key_version": "1",
            "bearer_token": "your-bearer-token",
            "base_urls": {
              "sponsored-products": "https://developer.api.walmart.com/api-proxy/service/WPA/Api/v1",
              "display": "https://developer.api.walmart.com/api-proxy/service/display/api/v1"
            }
          }
        }
      }
    }
  }
}
```

| Field | Notes |
|---|---|
| `consumer_id` | Partner Network consumer ID |
| `private_key` | Path to the RSA private key (PEM); relative paths resolve against the config directory |
| `private_key_version` | Key version string (default `"1"`) |
| `bearer_token` | OAuth bearer token |
| `base_urls.<api>` | One per api in the platform's discovery surface. Keys may be bare (`sponsored-products`) or fully qualified (`walmart:ads:sponsored-products`). Extra keys are allowed for the auxiliary specs reached by raw method+path |

Environment names are free-form for these platforms — Walmart may issue a tenant only
`production`, or `production` + `staging`.

**OAuth2 platform** (`walmart:marketplace`):

```json
{
  "platforms": {
    "walmart:marketplace": {
      "regions": {
        "us": {
          "production": {
            "credentials": [
              {
                "client_id": "your-client-id",
                "client_secret": "your-client-secret",
                "advertisers": [
                  { "id": 7060158, "partner_id": "10001234" },
                  { "id": 7060159 }
                ]
              }
            ]
          }
        }
      }
    }
  }
}
```

Advertiser ids nest under the credential that serves them, so a secret appears exactly
once and a dangling advertiser reference is structurally impossible. `partner_id` is
per-seller because two `payments` operations require it as `WM_PARTNER_ID`. Base URLs are
fixed by the server and absent from the file; `environment` must be `production` or
`sandbox`.

Regions are a namespace, not a route — for `walmart:marketplace` every region reaches the
same hosts. The level exists because advertiser ids are only unique within a region.

### Splitting the config

A populated `walmart:marketplace` block can be tens of kilobytes of credentials —
88% of the file here — and a stray comma while editing it takes down every platform,
because a parse failure happens before any per-platform validation. So platforms may
live in drop-in files under `config.d/`, merged over the base:

```
~/.config/mcp-walmart-ads/
├── config.json                  # server-wide settings, and any platforms you like
├── config.d/
│   ├── walmart-marketplace.json # only a "platforms" object
│   └── samsclub-ads.json
└── keys/
```

- A drop-in may declare **only** `platforms`; server-wide settings stay in `config.json`.
- A platform declared in two files is an **error naming both** — never silent precedence.
- Only `*.json` directly in `config.d/` is read, so `.bak` and editor swap files are ignored.
- A file that fails to parse costs **only its own platforms**; the rest keep working.
- Relative `private_key` paths resolve against `config.json`'s directory either way, so
  moving a platform into `config.d/` needs no path edits.
- No `config.d/` directory means no change in behavior.

Read `wmt://config` to see which platforms loaded, which are unusable and from which
file, and any file that could not be parsed.

> **The config is read once at startup.** A corrected file needs the server restarted.

### Top-level options

| Field | Default | Notes |
|---|---|---|
| `response_cache_ttl` | `3600` | Seconds a truncated body or download stays readable at its resource URI |
| `truncate_threshold` | `1024` | Response bytes returned inline before truncating to a preview |

### Market → tenant (`wap-tenant-id`)

Pass `tenant` on `call_endpoint` / `download_file` for non-US `walmart:ads` markets
(e.g. `WMT_CA`, `WMT_MX`, `WBD_OD`). Omit for US and for `walmart:marketplace`.

## Tools

### `list_endpoints`

List operations across every api, with optional filters.

| Parameter | Notes |
|---|---|
| `query` | Case-insensitive substring on operation id, path, or summary |
| `api` | Limit to one api, e.g. `walmart:marketplace:order-management` |
| `platform` | Limit to one platform — `walmart:ads`, `walmart:marketplace`, `samsclub:ads` (schema enum) |
| `tag` | Filter by OpenAPI tag |
| `method` | Filter by HTTP verb — `GET`, `POST`, `PUT`, `PATCH`, `DELETE` (schema enum) |

Returned operation ids are qualified (`api:operationId`) and can be passed straight to
`describe_endpoint` or `call_endpoint`.

### `describe_endpoint`

One operation plus every `components.s