mcp-walmart-marketplace

# Walmart Marketplace APIs

[![CI](https://github.com/alyiox/mcp-walmart-marketplace/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/alyiox/mcp-walmart-marketplace/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/mcp-walmart-marketplace.svg)](https://pypi.org/project/mcp-walmart-marketplace/)
[![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-marketplace -->

MCP server for [Walmart Marketplace APIs](https://developer.walmart.com/us-marketplace/docs/introduction-to-marketplace-apis) — items, orders, inventory, prices, promotions, feeds, reports, returns, fulfillment, and more.

Exposes spec-driven discovery (`list_endpoints`, `describe_endpoint`), a generic API proxy (`call_endpoint`), feed upload and file download helpers, and a runtime spec refresher (`refresh_specs`). The AI agent discovers endpoints from bundled OpenAPI specs then calls them; the server handles OAuth2 token acquisition, refresh, and Walmart's required headers automatically. Base addresses are hardcoded per environment, so the config file carries nothing but credentials.

## Features

- **Spec-driven discovery** — 28 bundled OpenAPI specs covering 234 operations, refreshable at runtime
- **Any endpoint** — call by operation id or raw method+path; no code changes when APIs evolve
- **Automatic OAuth2** — tokens fetched, cached per credential, refreshed before expiry, retried once on 401. The client secret never leaves token acquisition
- **Multi-advertiser** — many seller credentials per region and environment, selected per call
- Multi-region, multi-environment — production and sandbox
- Required Walmart headers (`WM_SEC.ACCESS_TOKEN`, `WM_SVC.NAME`, `WM_QOS.CORRELATION_ID`, `WM_MARKET`, `WM_GLOBAL_VERSION`, `WM_SANDBOX`, `WM_PARTNER_ID`) injected server-side and hidden from the agent
- Large responses truncated with full data available via MCP resource URI

## Requirements

- Python 3.13+
- Walmart Marketplace client ID and client secret per seller ([Developer Portal](https://developer.walmart.com/))

## 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-marketplace
```

```bash
# Or run from source
git clone https://github.com/alyiox/mcp-walmart-marketplace.git
cd mcp-walmart-marketplace
uv sync
npx -y @modelcontextprotocol/inspector uv run mcp-walmart-marketplace
```

## Configuration

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

> **Windows note:** `~` maps to `%USERPROFILE%`, so the full path is
> `%USERPROFILE%\.config\mcp-walmart-marketplace\config.json`.

**1. Create the config directory and copy the example**

```bash
mkdir -p ~/.config/mcp-walmart-marketplace
cp config.example.json ~/.config/mcp-walmart-marketplace/config.json
```

**2. Edit `~/.config/mcp-walmart-marketplace/config.json`**

```json
{
  "response_cache_ttl": 3600,
  "truncate_threshold": 1024,
  "regions": {
    "primary": {
      "production": {
        "credentials": [
          {
            "client_id": "11111111-2222-3333-4444-555555555555",
            "client_secret": "acme-client-secret-goes-here",
            "advertisers": [
              { "id": 1000001, "partner_id": "10000000001" },
              { "id": 1000002 }
            ]
          }
        ]
      },
      "sandbox": {
        "credentials": [
          {
            "client_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
            "client_secret": "acme-sandbox-client-secret-goes-here",
            "advertisers": [{ "id": 1000001 }]
          }
        ]
      }
    }
  }
}
```

| 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>` | Region label — case-insensitive, free-form. Groups advertisers; it does not change which host is called |
| `regions.<R>.<E>` | Environment — exactly `production` or `sandbox` |
| `…<E>.credentials[]` | One entry per Walmart client credential |
| `…credentials[].client_id` | Walmart client ID (UUID) |
| `…credentials[].client_secret` | Walmart client secret, as plain text |
| `…credentials[].advertisers` | Sellers this credential serves, each `{"id": …}` with an optional `"partner_id"` |

Keep the config file readable only by you — it holds client secrets in plain text.

Everything else is fixed by the server: base URLs (`marketplace.walmartapis.com` for production, `sandbox.walmartapis.com` for sandbox), `WM_SVC.NAME`, the `client_credentials` grant, and the per-operation `WM_MARKET` / `WM_SANDBOX` header values.

### Regions

A region is a namespace, not a route. Base addresses are fixed by the server per environment, so every region reaches the same Walmart hosts. The level exists so advertiser ids only have to be unique within one region — the same id under two regions can mean different sellers with different credentials.

### Partner IDs

Add `partner_id` to a seller that has a Walmart Partner ID:

```json
"advertisers": [
  { "id": 1000001, "partner_id": "10000000001" },
  { "id": 1000002 }
]
```

Two `payments` operations — `payments:getTaxForms` and `payments:downloadTaxForm` — require it as the `WM_PARTNER_ID` header. Calling one for a seller configured without a partner id fails with a message telling you to add it, rather than a Walmart 400. Every other operation ignores it, so most entries are just `{"id": …}`.

### Advertisers

`advertiser_id` is **required** on every tool that reaches the network; there is no default. Read the `wmm://config` resource to discover which advertiser ids are configured. It reports region, environment, and advertiser ids only — never client ids or secrets.

## Tools

| Tool | Purpose |
|---|---|
| `list_endpoints` | List operations across the bundled specs, filtered by query, domain, tag, or method |
| `describe_endpoint` | One operation plus its schema closure, with server-managed headers stripped |
| `call_endpoint` | Execute any operation by id or raw method+path |
| `upload_feed` | Upload a feed file (multipart) for a feed type |
| `download_file` | Download a report, label, or other binary to a local path |
| `refresh_specs` | Re-pull specs from the ReadMe api-registry into the user cache |

## Resources

| URI | Contents |
|---|---|
| `wmm://config` | Configured regions, environments, and advertiser ids |
| `wmm://responses/{request_id}` | Full body of a truncated response |
| `wmm://curl/{request_id}` | Equivalent cURL command for a previous request |

## MCP host examples

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "walmart-marketplace": {
      "command": "uvx",
      "args": ["mcp-walmart-marketplace"]
    }
  }
}
```

### Claude Code

Add to your Claude Code MCP config:

```json
{
  "mcpServers": {
    "walmart-marketplace": {
      "command": "uvx",
      "args": ["mcp-walmart-marketplace"]
    }
  }
}
```

### Codex

```toml
[mcp_servers.walmart-marketplace]
command = "uvx"
args = ["mcp-walmart-marketplace"]
```

### OpenCode

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

### GitHub Copilot

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

## Specs

The 28 bundled specs come from the ReadMe api-registry that backs
`developer.walmart.com`. They load from the user cache dir first
(`~/.cache/mcp-walmart-marketplace/specs/`) and fall back to the copy shipped in
the wheel, so `refresh_specs` takes effect immediately without a reinstall.

The files on disk are stored **verbatim** as the registry served them, so the
bundle is the source of truth and a refresh diff shows exactly what Walmart
changed. Reduction happens on load, which keeps it a runtime policy rather than
something baked into the files:

- **Oversized examples are dropped.** There are 3,514 inline `example` payloads
  totalling 4.13 MB, but the median is 16 bytes and two `/v3/items/taxonomy`
  payloads account for 3.25 MB. Everything at or under `MAX_EXAMPLE_BYTES`
  (1 KB) survives — 97% of them, for ~133 KB — so format hints for dates, skus,
  and identifiers stay available while the monsters never reach an agent.
- **`x-readme` is removed** — docs-platform rendering metadata, not API detail.

Cost of loading all 28 specs is ~80 ms once per process; results are cached per
spec and invalidated by file mtime, so a `refresh_specs` takes effect
immediately. `describe_endpoint` output is 5.1 KB at the median and 88 KB at the
worst (six `order-management` operations inline very large response schemas).

To rebuild the bundled copies:

```bash
uv run python scripts/fetch_specs.py            # all
uv run python scripts/fetch_specs.py order-management
```

## Caveats

**The specs and the API disagree about authentication.** 76 operations declare a Basic `Authorization` header built from the client id and secret, and `fulfillment-management` and `insights-management` appear to require it *instead of* an access token. Probed against production, that is wrong: Basic alone returns 401, the access token alone returns 200, on every service tested. This server therefore sends `WM_SEC.ACCESS_TOKEN` on every request and never sends the client secret anywhere except `/v3/token`. If you diff its behavior against the reference docs, that gap is deliberate.

**`WM_SVC.NAME` cannot be read from the specs.** 103 operations declare the literal placeholder string `"Walmart Se