Walmart Marketplace APIs

MCP-Server für Walmart Marketplace APIs — Artikel, Bestellungen, Inventar, Preise, Aktionen, Feeds, Berichte, Retouren, Fulfillment und mehr.

Ermöglicht spezifikationsgesteuerte Erkennung (list_endpoints, describe_endpoint), einen generischen API-Proxy (call_endpoint), Helfer für Feed-Upload und Dateidownload sowie einen Laufzeit-Spec-Aktualisierer (refresh_specs). Der KI-Agent entdeckt Endpunkte aus den gebündelten OpenAPI-Spezifikationen und ruft sie dann auf; der Server übernimmt automatisch OAuth2-Token-Beschaffung, -Erneuerung und die von Walmart benötigten Header. Basisadressen sind pro Umgebung fest codiert, daher enthält die Konfigurationsdatei nichts außer Anmeldedaten.

Features

• Spezifikationsgesteuerte Erkennung — 28 gebündelte OpenAPI-Spezifikationen mit 234 Operationen, zur Laufzeit aktualisierbar

• Beliebiger Endpunkt — Aufruf über Operations-ID oder rohe Methode+Pfad; keine Codeänderungen, wenn sich APIs weiterentwickeln

• Automatisches OAuth2 — Tokens werden abgerufen, pro Anmeldedatensatz zwischengespeichert, vor Ablauf erneuert und bei 401 einmal wiederholt. Das Client-Secret verlässt nie die Token-Beschaffung

• Multi-Advertiser — viele Verkäufer-Anmeldedaten pro Region und Umgebung, pro Aufruf auswählbar

• Multi-Region, Multi-Umgebung — Produktion und Sandbox

• Erforderliche Walmart-Header (WM_SEC.ACCESS_TOKEN, WM_SVC.NAME, WM_QOS.CORRELATION_ID, WM_MARKET, WM_GLOBAL_VERSION, WM_SANDBOX, WM_PARTNER_ID) werden serverseitig eingefügt und vor dem Agenten verborgen

• Große Antworten werden gekürzt; die vollständigen Daten sind über eine MCP-Ressourcen-URI verfügbar

Related MCP server: MoySklad MCP Server

Requirements

• Python 3.13+

• Walmart-Marketplace-Client-ID und Client-Secret pro Verkäufer (Entwicklerportal)

Quick start

Richten Sie Ihre Konfiguration ein (siehe Konfiguration) und starten Sie dann den Server:

# Run directly with uvx (no clone needed)
npx -y @modelcontextprotocol/inspector uvx mcp-walmart-marketplace

# 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

Die Konfigurationsdatei liegt unter Ihrem Home-Verzeichnis unter ~/.config/mcp-walmart-marketplace/config.json.

Windows-Hinweis: ~ wird auf %USERPROFILE% abgebildet, der vollständige Pfad ist also %USERPROFILE%\.config\mcp-walmart-marketplace\config.json.

1. Erstellen Sie das Konfigurationsverzeichnis und kopieren Sie das Beispiel

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

2. Bearbeiten Sie ~/.config/mcp-walmart-marketplace/config.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 }]
          }
        ]
      }
    }
  }
}

Halten Sie die Konfigurationsdatei nur für sich selbst lesbar – sie enthält Client-Secrets im Klartext.

Alles andere ist vom Server festgelegt: Basis-URLs (marketplace.walmartapis.com für Produktion, sandbox.walmartapis.com für Sandbox), WM_SVC.NAME, der client_credentials-Grant und die pro Operation festgelegten WM_MARKET- / WM_SANDBOX-Headerwerte.

Regions

Eine Region ist ein Namensraum, keine Route. Die Basisadressen sind vom Server pro Umgebung festgelegt, daher erreicht jede Region dieselben Walmart-Hosts. Die Ebene existiert, damit Advertiser-IDs nur innerhalb einer Region eindeutig sein müssen – dieselbe ID unter zwei Regionen kann verschiedene Verkäufer mit verschiedenen Anmeldedaten bedeuten.

Partner IDs

Fügen Sie partner_id zu einem Verkäufer hinzu, der eine Walmart-Partner-ID hat:

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

Zwei payments-Operationen – payments:getTaxForms und payments:downloadTaxForm – benötigen sie als WM_PARTNER_ID-Header. Wenn Sie eine davon für einen Verkäufer aufrufen, der ohne Partner-ID konfiguriert ist, schlägt der Aufruf mit einer Meldung fehl, die Sie auffordert, sie hinzuzufügen, statt mit einem Walmart-400. Jede andere Operation ignoriert sie, daher sind die meisten Einträge nur {"id": …}.

Advertisers

advertiser_id ist bei jedem Tool, das das Netzwerk erreicht, erforderlich; es gibt keinen Standardwert. Lesen Sie die Ressource wmm://config, um herauszufinden, welche Advertiser-IDs konfiguriert sind. Sie meldet nur Region, Umgebung und Advertiser-IDs – niemals Client-IDs oder Secrets.

Tools

Resources

MCP host examples

Cursor

Hinzufügen zu .cursor/mcp.json:

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

Claude Code

Hinzufügen zu Ihrer Claude-Code-MCP-Konfiguration:

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

Codex

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

OpenCode

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

GitHub Copilot

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

Specs

Die 28 gebündelten Spezifikationen stammen aus der ReadMe-api-registry, die developer.walmart.com unterstützt. Sie werden zuerst aus dem Benutzer-Cache-Verzeichnis geladen (~/.cache/mcp-walmart-marketplace/specs/) und fallen auf die im Wheel mitgelieferte Kopie zurück, sodass refresh_specs sofort wirkt, ohne Neuinstallation.

Die Dateien auf der Platte werden wörtlich so gespeichert, wie die Registry sie ausgeliefert hat. Das Bundle ist also die Quelle der Wahrheit, und ein Refresh-Diff zeigt genau, was Walmart geändert hat. Die Reduktion erfolgt beim Laden, was sie zu einer Laufzeitrichtlinie macht und nicht zu etwas, das in die Dateien eingebacken ist:

• Übergroße Beispiele werden entfernt. Es gibt 3.514 Inline-example-Payloads mit insgesamt 4,13 MB, aber der Median liegt bei 16 Bytes und zwei /v3/items/taxonomy-Payloads machen 3,25 MB aus. Alles bis einschließlich MAX_EXAMPLE_BYTES (1 KB) bleibt erhalten – 97 % davon, für ~133 KB – sodass Format-Hinweise für Daten, SKUs und Kennungen verfügbar bleiben, während die Monster nie einen Agenten erreichen.

• x-readme wird entfernt – Rendering-Metadaten der Dokumentationsplattform, keine API-Details.

Das Laden aller 28 Spezifikationen kostet ~80 ms einmal pro Prozess; die Ergebnisse werden pro Spezifikation zwischengespeichert und anhand der Datei-Mtime ungültig gemacht, sodass ein refresh_specs sofort wirkt. Die Ausgabe von describe_endpoint hat im Median 5,1 KB und im schlimmsten Fall 88 KB (sechs order-management-Operationen betten sehr große Antwortschemata ein).

Um die gebündelten Kopien neu zu erstellen:

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

Caveats

Die Spezifikationen und die API sind sich bezüglich der Authentifizierung uneinig. 76 Operationen deklarieren einen Basic-Authorization-Header, der aus Client-ID und -Secret aufgebaut ist, und fulfillment-management und insights-management scheinen ihn anstelle eines Zugriffstokens zu benötigen. Gegen die Produktion getestet, ist das falsch: Basic allein liefert 401, das Zugriffstoken allein liefert 200, bei jedem getesteten Dienst. Dieser Server sendet daher bei jeder Anfrage WM_SEC.ACCESS_TOKEN und sendet das Client-Secret nirgendwohin außer an /v3/token. Wenn Sie sein Verhalten mit der Referenzdokumentation vergleichen, ist diese Abweichung beabsichtigt.

WM_SVC.NAME kann nicht aus den Spezifikationen gelesen werden. 103 Operationen deklarieren den wörtlichen Platzhalter "Walmart Service Name" und nur 100 den echten Wert, daher ist er auf Walmart Marketplace festgelegt, was Live-Aufrufe bestätigen.

Nicht jeder dokumentierte Endpunkt ist mit Verkäufer-Anmeldedaten erreichbar. GET /v3/utilities/apiStatus liefert HTTP 520 Unable to route request und nennt wm_svc.name: PARTNERMANAGEMENTSERVICES und wm_svc.env: prod als erwartete Header – aber das Senden genau dieser liefert weiterhin 520. Es scheint zu einem Dienst zu gehören, den 3P-Anmeldedaten nicht erreichen können, und die Fehlermeldung ist eine Irreführung. Erwarten Sie eine Handvoll ähnlicher Fälle unter 234 Operationen.

Berichts-Endpunkte verhandeln Inhalte strikt. Sie lehnen Accept: */* mit einem 406 ab, das auflistet, was sie erzeugen können. Daher wird Accept aus den Medientypen abgeleitet, die die Operation für ihre Erfolgsantworten deklariert (bevorzugt application/json, wenn angeboten). Wenn Sie einen Endpunkt hinzufügen, dessen Spezifikation keinen Antwortinhalt deklariert, fällt er auf */* zurück und kann 406 liefern.

Die Live-Abdeckung ist dünn. Sieben Operationen aus fünf Domänen haben gegen die Produktion 200 zurückgegeben – feed-management, advertising, fulfillment-management, insights-management, settings-management – darunter zwei Berichts-Downloads, die als echte Excel-Arbeitsmappen ankommen. Die anderen ~227 sind aus den Spezifikationen verdrahtet und wurden nie aufgerufen. Erkennung und Anfragekonstruktion sind durch Tests abgedeckt; das Verhalten der vorgelagerten Systeme nicht.

Zwei bekannte Upstream-Fehler, keiner davon ein Client-Bug: fulfillment-management:getInventoryHealthReport antwortet mit 520 WFS_INTERNAL_SERVER_ERROR, und feed-management:getFeedErrorReport antwortet mit 404 für einen Feed, der sauber verarbeitet wurde.

Sandbox ist unverifiziert. Walmart stellt Sandbox-Anmeldedaten getrennt von der Produktion aus, und hier ist nichts gegen sandbox.walmartapis.com gelaufen. Die WM_SANDBOX: v2-Behandlung – die sich für die dynamische Sandbox entscheidet und die Antwort-Semantik ändert, statt nur zu routen – ist aus den Spezifikationen implementiert, nicht beobachtet.

upload_feed ist nicht Ende-zu-Ende getestet. Es wird nur durch Unit-Tests gegen einen skripteten Transport ausgeübt – der einzige Weg, es live zu verifizieren, ist das Einreichen eines echten Feeds, was einen Live-Katalog verändert. download_file wurde gegen die Produktion verifiziert.

Der Cross-Host-Redirect-Pfad ist ungetestet. download_file verwirft Anmeldedaten, wenn eine Weiterleitung den Host von Walmart verlässt, was relevant ist, falls ein Bericht jemals aus signiertem Speicher ausgeliefert wird. Jeder bisher beobachtete Download hat seine Bytes direkt in einem Hop zurückgegeben, daher hat dieser Zweig nur Unit-Test-Abdeckung.

License

MIT