# walmart-marketplace-mcp

An [MCP](https://modelcontextprotocol.io) server that lets you manage a Walmart Marketplace (Seller) account in plain language from any MCP-compatible client (Claude Desktop, Cursor, etc.). It exposes **22 tools** spanning the full seller workflow: **orders** (list, ship, cancel, refund), **inventory**, **items/products**, **pricing**, **customer returns**, **WFS / Walmart Fulfillment Services** (inbound shipments, labels, warehouse inventory), and **on-request reports** (item, inventory, performance, buy-box, and more).

It handles Walmart's OAuth 2.0 token flow for you: it exchanges your client ID/secret for a short-lived access token, caches it (~15 min), auto-refreshes it, and attaches the required `WM_SEC.ACCESS_TOKEN` / correlation-ID headers on every call. Credentials load from a local `.env` file (or your MCP client's env config), and the base URL is configurable so you can point it at production or Walmart's sandbox without a code change.

Built in Python with [FastMCP](https://github.com/modelcontextprotocol/python-sdk). Write actions (ship, cancel, refund, price/inventory changes, retire, inbound shipments) are flagged destructive, and the riskiest ones require explicit confirmation.

> **Disclaimer:** This is an independent, community-built project. It is **not affiliated with, endorsed by, or sponsored by Walmart Inc.** "Walmart" and "Walmart Marketplace" are trademarks of Walmart Inc. Use at your own risk — you are responsible for actions taken against your live seller account.

## Tools

**Orders**
- `walmart_list_orders` — list orders with status/SKU/date filters and cursor pagination
- `walmart_get_order` — full detail for one order by `purchaseOrderId`
- `walmart_acknowledge_order` — confirm receipt (required within 4h of an order)
- `walmart_ship_order` — mark line(s) shipped with tracking + carrier
- `walmart_cancel_order` — cancel line(s) *(destructive)*
- `walmart_refund_order` — refund line(s) *(destructive — moves money)*

**Items / Products**
- `walmart_list_items` — list catalog items with lifecycle/published filters
- `walmart_get_item` — item detail by SKU
- `walmart_retire_item` — remove a listing *(destructive, requires `confirm=true`)*

**Inventory**
- `walmart_get_inventory` — available quantity for a SKU
- `walmart_update_inventory` — set absolute quantity for a SKU

**Pricing**
- `walmart_update_price` — set selling price (with optional strike-through comparison price)

**Returns**
- `walmart_list_returns` — list customer returns with status/date filters
- `walmart_issue_return_refund` — refund line(s) of a return *(destructive — moves money)*

**WFS / Fulfillment** *(only relevant if you use Walmart Fulfillment Services)*
- `walmart_get_wfs_inventory` — on-hand stock in Walmart fulfillment centers
- `walmart_list_inbound_shipments` — list shipments sent to WFS
- `walmart_get_inbound_shipment_items` — per-SKU shipped vs received quantities
- `walmart_get_inbound_shipment_label` — WFS receiving label for a shipment
- `walmart_create_inbound_shipment` — create an inbound shipment *(requires `confirm=true`)*

**Reports (on-request)**
- `walmart_request_report` — kick off an async report (ITEM, INVENTORY, ITEM_PERFORMANCE, BUYBOX, etc.)
- `walmart_get_report_status` — poll status (RECEIVED → INPROGRESS → READY)
- `walmart_download_report` — get the presigned download URL once READY

## Prerequisites

- **Python 3.10+** (the MCP SDK requires it). On macOS, the system/Xcode Python may be too old — install a current one via [Homebrew](https://brew.sh) (`brew install python`) or [python.org](https://www.python.org/downloads/).
- **Walmart Marketplace API credentials** (client ID + secret) from the [Walmart Developer Portal](https://developer.walmart.com).

## Setup

```bash
git clone https://github.com/YOUR_USERNAME/walmart-marketplace-mcp.git
cd walmart-marketplace-mcp

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

Copy the env template and add your credentials:

```bash
cp .env.example .env
# then edit .env and fill in WALMART_CLIENT_ID and WALMART_CLIENT_SECRET
```

`WALMART_BASE_URL` defaults to production (`https://marketplace.walmartapis.com`). To test against Walmart's sandbox, set it to `https://sandbox.walmartapis.com` — no code change needed.

### Verify your credentials

```bash
python3 -c "import asyncio, walmart_seller_mcp as m; print('Auth OK, token length:', len(asyncio.run(m._get_access_token())))"
```

If you see `Auth OK`, you're good to go.

## Connect to Claude Desktop

Open **Settings → Developer → Edit Config** and add the server. Use **absolute paths**, and point `command` at the Python inside your virtualenv so it has the installed dependencies.

**macOS / Linux** — replace `/Users/you` with your actual home path:

```json
{
  "mcpServers": {
    "walmart-marketplace": {
      "command": "/Users/you/walmart-marketplace-mcp/.venv/bin/python",
      "args": ["/Users/you/walmart-marketplace-mcp/walmart_seller_mcp.py"]
    }
  }
}
```

**Windows** — replace `C:\\Users\\you` with your actual home path:

```json
{
  "mcpServers": {
    "walmart-marketplace": {
      "command": "C:\\Users\\you\\walmart-marketplace-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\you\\walmart-marketplace-mcp\\walmart_seller_mcp.py"]
    }
  }
}
```

Credentials are read from your `.env` file, so they don't need to go in this config. (Alternatively, you can drop a `"env": { "WALMART_CLIENT_ID": "...", "WALMART_CLIENT_SECRET": "..." }` block here instead of using `.env`.)

Fully quit and reopen Claude Desktop after editing the config — MCP servers only load on startup.

> **Tip:** don't know your exact path? Run `pwd` inside the project folder (macOS/Linux) or `cd` (Windows) and paste what it prints in place of the folder path above.

## Usage examples

Once connected, just ask your MCP client things like:

- "List my Walmart orders from the last 7 days"
- "What orders still need to ship?"
- "Set inventory for SKU ABC123 to 40 units"
- "Mark down SKU ABC123 to $24.99 from $40"
- "Ship order 1796277083022 — UPS tracking 1Z..."
- "Any open customer returns?"
- "Request an inventory report"

## Notes & safety

- **Quantities are absolute.** `walmart_update_inventory` sets the on-hand amount; it does not add or subtract.
- **Destructive tools are flagged** via MCP `destructiveHint`. `walmart_retire_item` and `walmart_create_inbound_shipment` additionally require `confirm=true`. Cancel/refund act per order line.
- **Orders window:** Walmart exposes ~180 days of order history.
- **Reports are async:** request → poll status (15–45 min) → download. Reports are retained 30 days.
- **WFS tools** only return data if you use Walmart Fulfillment Services; seller-fulfilled sellers can ignore them.
- **Token caching** is in-memory per process and refreshes automatically ~60s before expiry.
- Errors surface Walmart's own error body (truncated) so you can see exactly what it rejected.

## Local testing

```bash
# Inspect tools visually with the MCP Inspector:
npx @modelcontextprotocol/inspector python3 walmart_seller_mcp.py
```

## Contributing

Issues and PRs welcome. Some natural next additions:

- **Feeds API** for bulk price/inventory/item uploads (batch updates across many SKUs)
- **Promotions** management
- **Shipping templates / lag-time settings**

Please don't commit real credentials — `.env` is gitignored for that reason.

## License

[MIT](LICENSE)