Walmart Marketplace APIs

Servidor MCP para Walmart Marketplace APIs: artículos, pedidos, inventario, precios, promociones, feeds, informes, devoluciones, fulfillment y más.

Expone descubrimiento guiado por especificaciones (list_endpoints, describe_endpoint), un proxy de API genérico (call_endpoint), utilidades para subir feeds y descargar archivos, y un actualizador de especificaciones en tiempo de ejecución (refresh_specs). El agente de IA descubre los endpoints a partir de las especificaciones OpenAPI incluidas y luego los invoca; el servidor se encarga automáticamente de la obtención y renovación del token OAuth2 y de las cabeceras que Walmart exige. Las direcciones de base están fijadas por entorno, de modo que el archivo de configuración no contiene nada más que credenciales.

Características

• Descubrimiento guiado por especificaciones: 28 especificaciones OpenAPI integradas que cubren 234 operaciones, actualizables en tiempo de ejecución

• Cualquier endpoint: llama por id de operación o método y ruta en bruto; sin cambios de código cuando las API evolucionan

• OAuth2 automático: tokens capturados, almacenados en caché por credencial, renovados antes de la caducidad y reintentados una vez en caso de 401. El secreto del cliente nunca abandona la adquisición del token

• Multi-anunciante: varias credenciales de vendedor por región y entorno, seleccionadas en cada llamada

• Multi-región y multi-entorno: producción y sandbox

• Cabeceras obligatorias de Walmart (WM_SEC.ACCESS_TOKEN, WM_SVC.NAME, WM_QOS.CORRELATION_ID, WM_MARKET, WM_GLOBAL_VERSION, WM_SANDBOX, WM_PARTNER_ID) inyectadas en el servidor y ocultas del agente

• Las respuestas grandes se truncan, y los datos completos están disponibles mediante el recurso URI de MCP

Related MCP server: MoySklad MCP Server

Requisitos

• Python 3.13+

• Client ID y Client Secret de Walmart Marketplace por vendedor (Developer Portal)

Inicio rápido

Configura (consulta Configuración) y luego ejecuta el servidor:

# 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

Configuración

El archivo de configuración se encuentra en tu directorio personal: ~/.config/mcp-walmart-marketplace/config.json.

Nota para Windows: ~ se corresponde con %USERPROFILE%, por lo que la ruta completa es %USERPROFILE%\.config\mcp-walmart-marketplace\config.json.

1. Crea el directorio de configuración y copia el ejemplo

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

2. Edita ~/.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 }]
          }
        ]
      }
    }
  }
}

Mantén el archivo de configuración legible sólo para ti: contiene secretos de cliente en texto seco.

Todo lo demás lo fija el servidor: URLs base (marketplace.walmartapis.com para producción, sandbox.walmartapis.com para sandbox), WM_SVC.NAME, el órgran de concesión client_credentials y los valores de cabecera WM_MARKET / WM_SANDBOX por operación.

Regiones

Una región es un espacio de nombres, no una ruta. Las direcciones base son fijadas por el servidor por entorno, así que toda región llega a los mismos hosts de Walmart. La existencia de ese nivel sirve para que los identificadores de anunciante sólo tengan que ser únicos dentro de una única región: el mismo id en dos regiones puede corresponder a vendedores distintos, con credenciales distintas.

Partner IDs

Añade partner_id a un vendedor que tenga un Walmart Partner ID:

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

Dos operaciones payments – payments:getTaxForms y payments:downloadTaxForm – lo exigen como cabecera WM_PARTNER_ID. Si se llama a una de estas operaciones para un vendedor configurado sin partner ID, fallará con un mensaje que te pide que la añadas, en lugar de recibir un 400 de Walmart. El resto de operaciones lo ignoran, por lo que la mayoría de las entradas son simplemente {"id": …}.

Anunciantes

advertiser_id es obligatorio en todas las herramientas que acceden a la red; no existe un valor por defecto. Lee el recurso wmm://config para descubrir qué id de anunciantes están configurados. Ese recurso solo informa de región, entorno e ids de anunciante, nunca de client_id ni claves secretas.

Herramientas

Recursos

Ejemplos de host MCP

Cursor

Añade a .cursor/mcp.json:

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

Claude Code

Añade a tu configuración MCP de Claude Code:

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

Especificaciones

Las 28 especificaciones incluidas proceden del ReadMe api-registry que soporta developer.walmart.com. Se cargan primero desde el directorio de caché del usuario (~/.cache/mcp-walmart-marketplace/specs/) y, si están ausentes, desde la copia que viajar con la distribución (wheel). Así, refresh_specs surte efecto al instante sin necesidad de reinstalar.

Los archivos del disco se guardan verbatim, tal como los sirvió el registro, así que el paquete es la fuente de verdad real y el diff de refresco presenta exactamente lo que Walmart cambió. La reducción se produce en la carga, de modo que es una política en tiempo de ejecución, no algo incrustado en los archivos:

• Se descartan ejemplos demasiado grandes. Hay 3.514 carpas example en línea que suman 4,13 MB, pero la mediana es de 16 bytes y dos cargas /v3/items/taxonomy suman por sí solas 3,25 MB. Todo lo que está en o por debajo de MAX_EXAMPLE_BYTES (1 kB) sobrevive: el 97 % de ellos, es decir, ~133 KB, por lo que las pistas de formato de fechas, SKUs e ids siguen disponibles mientras que estos colosos no llegan nunca al agente.

• El x-readme se elimina: son metadatos de renderizado de la plataforma de documentación, no detalles de API.

Cargar las 28 especificaciones requiere ~80 ms una vez por proceso; los resultados se almacenan en caché por especificación y se invalidan según la hora de modificación del archivo, de modo que un refresh_specs se vuelve efectivo de inmediato. La salida de describe_endpoint es de 5,1 KB de media y de 88 KB en el peor caso (seis operaciones de order-management queincrustan esquemas de respuesta realmente grandes).

Para reconstruir las copias empaquetadas:

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

Advertencias

Las especificaciones y la API discrepan sobre autenticación. 76 operaciones declaran una cabecera de Basic Authorization elaborada a partir del id de cliente y de su secreto; fulfillment-management e insights-management parecen exigirla en lugar de un token de acceso. Probado ante producción, la afirmación es falsa: Basic solo da 401 y el token de acceso solo da 200, en todos los servicios probados. Por esta razón este servidor envía WM_SEC.ACCESS_TOKEN en cada petición y nunca envía el secreto de cliente en ningún sitio salvo a /v3/token. Si comparas el comportamiento con los documentos de referencia, verás que ese hueco está puesto adrede.

WM_SVC.NAME no puede extraerse de las especificaciones. 103 operaciones declaran la cadena literal que hace de marcador "Walmart Service Name" y solo 100 el valor real, así que se fija como Walmart Marketplace; las llamadas en vivo lo confirman.

No todos los endpoints documentados son alcanzables con credenciales de vendedor. GET /v3/utilities/apiStatus devuelve HTTP 520 Unable to route request y solicita las cabeceras wm_svc.name: PARTNERMANAGEMENTSERVICES y wm_svc.env: prod, pero aun enviando exactamente esas, sigue devolviendo 520. Parece pertenecer a un servicio al que las credenciales 3P no tienen acceso, y el mensaje de error es un señuelo. Cabe esperar un puñado de casos similares en las 234 operaciones.

Los informes negocian el contenido de forma estricta. Rechazan Accept: */* con un 406 en el que enumeran lo que pueden producir; por tanto Accept se deduce de los media types que la operación declara para sus respuestas de éxito (prefiriendo application/json cuando se ofrece). Si añades un endpoint cuya especificación no declare contenido de respuesta, quedará sin cubrir por su */* y puede devolver 406.

La cobertura en vivo es escasa. Siete operaciones de cinco dominios han devuelto 200 contra producción: feed-management, advertising, fulfillment-management, insights-management, settings-management, incluidos dos informes descargados como libros de Excel reales. El resto, unas ~227, están cableadas desde las especificaciones y nunca se han llamado. El descubrimiento y la construcción de peticiones están cubiertos por pruebas; el comportamiento en el subsistema ascendente no.

Dos fallos conocidos en el lado ascendente, ninguno por nuestro algoritmo: fulfillment-management:getInventoryHealthReport responde 520 WFS_INTERNAL_SERVER_ERROR, y feed-management:getFeedErrorReport responde 404 para un feed que se procesó limpiamente.

El sandbox no está verificado. Walmart emite credenciales de sandbox por separado de las de producción; nada de esto se ha ejecutado contra sandbox.walmartapis.com. El tratamiento de WM_SANDBOX: v2 (que opta por el sandbox dinámico y cambia la semántica de las respuestas, no solo el enrutamiento) se ha implementado a partir de los specs, no de la observación.

upload_feed no está probado de extremo a extremo. Solo se ejecutan pruebas unitarias sobre un transporte simulado: el único método para verificarlo en vivo es enviar un feed real, lo que altera un catálogo activo. download_file en cambio sí se ha verificado contra producción.

La ruta de redirección entre hosts no se ha ejercido. download_file elimina credenciales cuando una redirección sale del host de Walmart, lo cual tiene importancia si un día un informe se sirve desde almacenamiento firmado. Hasta ahora todas las descargas observadas devuelven sus bytes directamente y de un solo salto, así que esa rama solo tiene esa prueba unitaria.

Licencia

MIT