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?

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)

Marketplace (seller)

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

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).