walmart-marketplace-mcp

An MCP 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. 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 (brew install python) or python.org.
• Walmart Marketplace API credentials (client ID + secret) from the Walmart Developer Portal.

Setup

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:

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

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:

{
  "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:

{
  "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

# 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