walmart-mcp

walmart-mcp

A TypeScript Walmart API client, delivered as an MCP server (stdio) with a reusable SDK underneath. It wraps two Walmart APIs behind one client:

• Marketplace (seller) — manage your Walmart Marketplace catalog: items, inventory, prices,

and orders. OAuth 2.0.

• Affiliate / Catalog (consumer) — search the public Walmart catalog: product search,

lookup, taxonomy, trending, reviews, and store locator. Read-only, RSA-signature auth.

Configure either or both surfaces. Tools register only for the surfaces you've configured.

Why this one

• Importable SDK, not just a server. client/ + api/ are a standalone, fully unit-tested

Walmart SDK with zero MCP knowledge — import { WalmartSdk } and use it in any Node project. The MCP server is a thin wrapper.

• Minimal footprint. Two runtime deps total (@modelcontextprotocol/sdk + zod). RSA

signing and correlation UUIDs use Node's built-in crypto; .env is loaded via --env-file, no dotenv/node-rsa/uuid.

• Two auth schemes done right. Marketplace's OAuth token is cached and auto-refreshed on

401; the Affiliate signature is regenerated (with a fresh timestamp) on every request.

• Curated outputs. Search/list tools return compact, schema-validated structuredContent

instead of raw, deeply-nested Walmart payloads, so agents don't shell out to parse JSON.

Which surface do I want?

| You are… | Use | Credentials from | Auth | |---|---|---|---| | A Walmart seller managing your listings/orders | Marketplace | developer.walmart.com → API Key Management | OAuth 2.0 (Client ID + Secret) | | An affiliate / app reading the public catalog | Affiliate | walmart.io (program approval required) | RSA signature (Consumer ID + private key) |

Setup

1. Install & build

npm install
npm run build

2. Configure credentials

cp .env.example .env   # then fill in whichever surface(s) you use

# Marketplace (seller)
WALMART_CLIENT_ID=...
WALMART_CLIENT_SECRET=...

# Affiliate / Catalog (consumer)
WALMART_CONSUMER_ID=...
WALMART_PRIVATE_KEY=...        # single-line Base64 PKCS#8 from the portal (or a full PEM)
WALMART_KEY_VERSION=1

The server reads credentials from its environment; it does not auto-load .env. Your MCP client supplies them via the config env block (step 4). For the CLI and standalone runs, Node's --env-file=.env loads them (the npm run check / npm start scripts do this).

Notes:

• Private key handling. WALMART_PRIVATE_KEY accepts the single-line Base64 key the

Walmart.io portal issues, or a full -----BEGIN PRIVATE KEY----- PEM. It's never logged. The matching public key is uploaded to the portal; WALMART_KEY_VERSION is shown next to it.

• Marketplace tokens are short-lived (~15 min) and cached in your OS data dir

($XDG_DATA_HOME/walmart-mcp on Unix, %APPDATA%\walmart-mcp on Windows; files chmod 0600), then auto-refreshed on use.

3. Validate (optional but recommended)

npm run check

Mints a Marketplace token (proves CLIENT_ID/SECRET) and signs a live Affiliate request (proves CONSUMER_ID + private key), skipping whichever surface you didn't configure. Expected output:

Marketplace  validating OAuth client credentials… OK
Affiliate    signing a taxonomy request… OK
✅ Configured surfaces validated. The MCP server reuses these same credentials.

4. Register with your MCP client

{
  "mcpServers": {
    "walmart": {
      "command": "node",
      "args": ["/absolute/path/to/walmart-mcp/dist/mcp/server.js"],
      "env": {
        "WALMART_CLIENT_ID": "...",
        "WALMART_CLIENT_SECRET": "...",
        "WALMART_CONSUMER_ID": "...",
        "WALMART_PRIVATE_KEY": "...",
        "WALMART_KEY_VERSION": "1"
      }
    }
  }
}

5. Run

Your MCP client launches node dist/mcp/server.js, injects the env vars, and the server registers the tools for each configured surface. (To run standalone for testing: npm start.)

Tools

Affiliate / Catalog (read-only)

| Tool | Purpose | |------|---------| | affiliate_search | Full-text catalog search (compact results) | | affiliate_product_lookup | Look up products by item id(s), UPC, or GTIN | | affiliate_taxonomy | The catalog category tree | | affiliate_trending | Currently trending products | | affiliate_reviews | Customer reviews for a product | | affiliate_stores | Walmart stores near a lat/long, city, or ZIP |

Marketplace (seller)

| Tool | Auth | Purpose | |------|------|---------| | mp_get_items | OAuth | List your catalog (compact, cursor-paginated) | | mp_get_item | OAuth | One catalog item by SKU | | mp_get_inventory | OAuth | A SKU's on-hand inventory | | mp_update_inventory | OAuth | Write: set a SKU's available quantity | | mp_update_price | OAuth | Write: update a SKU's price | | mp_get_orders | OAuth | List orders by date/status (compact, cursor-paginated) | | mp_get_order | OAuth | One order by purchaseOrderId | | mp_acknowledge_order | OAuth | Write: acknowledge an order (required before shipping) |

Search/list tools return compact, structured results (structuredContent validated by an output schema) — just the fields the workflow needs — rather than the raw, deeply-nested Walmart payload.

Troubleshooting

| Symptom | Cause / fix | |---------|-------------| | Server logs "No Walmart credentials found" | Neither surface configured. Fill the config env block (MCP) or .env (standalone). | | A tool returns "… credentials are not configured" | That surface's env vars are missing; the other surface still works. | | 401 / token errors on Marketplace | Client ID/Secret wrong or revoked. Re-check with npm run check. The client already refreshes a normal expiry automatically. | | 401 / signature errors on Affiliate | Wrong Consumer ID, key version, or private key; or large clock skew (timestamp TTL ≈ 180s). Verify with npm run check. | | "Could not parse the affiliate private key" | WALMART_PRIVATE_KEY isn't the Base64 PKCS#8 portal key or a valid PEM. | | MCP server won't start / behaves like old code | dist/ is missing or stale — the MCP launch runs the built file and does not auto-build. Run npm run build. | | --env-file=.env errors with ENOENT | .env doesn't exist. cp .env.example .env and fill it in. |

Development

npm test         # vitest (fetch mocked, throwaway RSA keypair) — no credentials needed
npm run typecheck
npm run build    # also runs on install (prepare) and before start/check

Architecture

src/
  client/   WalmartClient, marketplaceAuth (OAuth), affiliateAuth + signature (RSA),
            tokenStore, correlation, errors
  api/      marketplace/{items,inventory,prices,orders}, affiliate/catalog   (zero MCP knowledge)
  types/    request/response shapes
  mcp/      server.ts (stdio) + config.ts + tools.ts + format.ts
  sdk.ts    WalmartSdk facade

The client/ + api/ layers are a standalone SDK, fully unit-tested with fetch mocked; mcp/ is a thin wrapper. Import the SDK directly via the package root (WalmartSdk).