mcp-walmart-marketplace

Servidor MCP para las APIs de Walmart Marketplace (vendedor 3P en EE. UU.)

Documentación

APIs de Walmart Marketplace

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

Expone descubrimiento basado en especificaciones (list_endpoints, describe_endpoint), un proxy de API genérico (call_endpoint), asistentes de carga de feeds y descarga de archivos, y un actualizador de especificaciones en tiempo de ejecución (refresh_specs). El agente de IA descubre endpoints a partir de las especificaciones OpenAPI incluidas y luego los invoca; el servidor gestiona automáticamente la obtención de tokens OAuth2, su renovación y los encabezados requeridos por Walmart. Las direcciones base están fijadas por entorno, por lo que el archivo de configuración solo contiene credenciales.

Características

Descubrimiento basado en especificaciones: 28 especificaciones OpenAPI incluidas que cubren 234 operaciones, actualizables en tiempo de ejecución
Cualquier endpoint: invocación por ID de operación o método+ruta sin procesar; sin cambios de código cuando las APIs evolucionan
OAuth2 automático: los tokens se obtienen, se almacenan en caché por credencial, se renuevan antes de expirar y se reintentan una vez ante un 401. El secreto del cliente nunca sale de la obtención de tokens
Multi-anunciante: múltiples credenciales de vendedor por región y entorno, seleccionadas en cada llamada
Multi-región, multi-entorno: producción y sandbox
Los encabezados requeridos por Walmart (WM_SEC.ACCESS_TOKEN, WM_SVC.NAME, WM_QOS.CORRELATION_ID, WM_MARKET, WM_GLOBAL_VERSION, WM_SANDBOX, WM_PARTNER_ID) se inyectan en el servidor y se ocultan al agente
Las respuestas grandes se truncan y los datos completos están disponibles mediante URI de recurso MCP

Requisitos

Python 3.13+
ID de cliente y secreto de cliente de Walmart Marketplace por vendedor (Portal para desarrolladores)

Inicio rápido

Configura tu configuración (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 en ~/.config/mcp-walmart-marketplace/config.json.

Nota para Windows: ~ se asigna a %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 }]
          }
        ]
      }
    }
  }
}

Campo de configuración	Descripción
`response_cache_ttl`	Segundos para mantener en memoria las respuestas truncadas (predeterminado: `3600`)
`truncate_threshold`	Límite de bytes de respuesta antes del truncamiento (predeterminado: `1024`)
`regions.<R>`	Etiqueta de región: no distingue mayúsculas, formato libre. Agrupa anunciantes; no cambia qué host se invoca
`regions.<R>.<E>`	Entorno: exactamente `production` o `sandbox`
`…<E>.credentials[]`	Una entrada por credencial de cliente de Walmart
`…credentials[].client_id`	ID de cliente de Walmart (UUID)
`…credentials[].client_secret`	Secreto de cliente de Walmart, en texto plano
`…credentials[].advertisers`	Vendedores a los que sirve esta credencial, cada `{"id": …}` con un `"partner_id"` opcional

Mantén el archivo de configuración legible solo por ti: contiene secretos de cliente en texto plano.

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

Regiones

Una región es un espacio de nombres, no una ruta. Las direcciones base las fija el servidor por entorno, por lo que cada región llega a los mismos hosts de Walmart. El nivel existe para que los ID de anunciante solo deban ser únicos dentro de una región: el mismo ID en dos regiones puede significar vendedores distintos con credenciales distintas.

ID de socio

Agrega partner_id a un vendedor que tenga un ID de socio de Walmart:

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

Dos operaciones de payments (payments:getTaxForms y payments:downloadTaxForm) lo requieren como encabezado WM_PARTNER_ID. Invocar una de ellas para un vendedor configurado sin ID de socio falla con un mensaje que te indica agregarlo, en lugar de un 400 de Walmart. Todas las demás operaciones lo ignoran, por lo que la mayoría de las entradas son solo {"id": …}.

Anunciantes

advertiser_id es obligatorio en cada herramienta que accede a la red; no hay valor predeterminado. Lee el recurso wmm://config para descubrir qué ID de anunciante están configurados. Informa solo región, entorno e ID de anunciante; nunca ID de cliente ni secretos.

Herramientas

Herramienta	Propósito
`list_endpoints`	Lista operaciones en las especificaciones incluidas, filtradas por consulta, dominio, etiqueta o método
`describe_endpoint`	Una operación más su cierre de esquema, con los encabezados gestionados por el servidor eliminados
`call_endpoint`	Ejecuta cualquier operación por ID o método+ruta sin procesar
`upload_feed`	Sube un archivo de feed (multipart) para un tipo de feed
`download_file`	Descarga un informe, etiqueta u otro binario a una ruta local
`refresh_specs`	Vuelve a extraer las especificaciones del registro de API de ReadMe en la caché del usuario

Recursos

URI	Contenido
`wmm://config`	Regiones, entornos e ID de anunciante configurados
`wmm://responses/{request_id}`	Cuerpo completo de una respuesta truncada
`wmm://curl/{request_id}`	Comando cURL equivalente para una solicitud anterior

Ejemplos de host MCP

Cursor

Agrega a .cursor/mcp.json:

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

Claude Code

Agrega 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 provienen del registro de API de ReadMe que respalda developer.walmart.com. Se cargan primero desde el directorio de caché del usuario (~/.cache/mcp-walmart-marketplace/specs/) y recurren a la copia incluida en el paquete, por lo que refresh_specs surte efecto de inmediato sin reinstalar.

Los archivos en disco se almacenan tal cual como los sirvió el registro, por lo que el paquete es la fuente de verdad y un diff de actualización muestra exactamente qué cambió Walmart. La reducción ocurre al cargar, lo que la convierte en una política de tiempo de ejecución en lugar de algo incorporado en los archivos:

Se descartan los ejemplos sobredimensionados. Hay 3,514 cargas útiles example en línea que suman 4.13 MB, pero la mediana es de 16 bytes y dos cargas útiles /v3/items/taxonomy representan 3.25 MB. Todo lo que esté en MAX_EXAMPLE_BYTES (1 KB) o menos sobrevive: el 97% de ellos, unos ~133 KB, por lo que las pistas de formato para fechas, SKU e identificadores siguen disponibles mientras que los monstruos nunca llegan a un agente.
Se elimina x-readme: metadatos de renderizado de la plataforma de documentación, no detalle de API.

El costo de cargar las 28 especificaciones es de ~80 ms una vez por proceso; los resultados se almacenan en caché por especificación y se invalidan por mtime de archivo, por lo que un refresh_specs surte efecto de inmediato. La salida de describe_endpoint es de 5.1 KB en la mediana y 88 KB en el peor caso (seis operaciones order-management incorporan esquemas de respuesta muy grandes en línea).

Para reconstruir las copias incluidas:

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

Advertencias

Las especificaciones y la API no coinciden en la autenticación. 76 operaciones declaran un encabezado Basic Authorization construido a partir del ID y el secreto del cliente, y fulfillment-management y insights-management parecen requerirlo en lugar de un token de acceso. Probado contra producción, eso es incorrecto: Basic solo devuelve 401, el token de acceso solo devuelve 200, en todos los servicios probados. Por lo tanto, este servidor envía WM_SEC.ACCESS_TOKEN en cada solicitud y nunca envía el secreto del cliente a ningún lugar excepto /v3/token. Si comparas su comportamiento con los documentos de referencia, esa diferencia es deliberada.

WM_SVC.NAME no se puede leer de las especificaciones. 103 operaciones declaran la cadena de marcador de posición literal "Walmart Service Name" y solo 100 el valor real, por lo que se fija en Walmart Marketplace, que las llamadas en vivo confirman.

No todos los endpoints documentados son accesibles con credenciales de vendedor. GET /v3/utilities/apiStatus devuelve HTTP 520 Unable to route request, nombrando wm_svc.name: PARTNERMANAGEMENTSERVICES y wm_svc.env: prod como los encabezados esperados, pero enviar exactamente esos aún devuelve 520. Parece pertenecer a un servicio al que las credenciales 3P no pueden acceder, y el mensaje de error es una pista falsa. Espera un puñado de casos similares entre las 234 operaciones.

Los endpoints de informes negocian el contenido de forma estricta. Rechazan Accept: */* con un 406 que enumera lo que pueden producir, por lo que Accept se deriva de los tipos de medios que la operación declara para sus respuestas exitosas (prefiriendo application/json cuando se ofrece). Si agregas un endpoint cuya especificación no declara contenido de respuesta, recurre a */* y puede devolver 406.

La cobertura en vivo es escasa. Siete operaciones en cinco dominios han devuelto 200 contra producción: feed-management, advertising, fulfillment-management, insights-management, settings-management; incluidas dos descargas de informes que llegan como libros de Excel reales. Las otras ~227 están conectadas desde las especificaciones y nunca se han invocado. El descubrimiento y la construcción de solicitudes están cubiertos por pruebas; el comportamiento ascendente no lo está.

Dos fallos ascendentes conocidos, ninguno un error del cliente: fulfillment-management:getInventoryHealthReport responde 520 WFS_INTERNAL_SERVER_ERROR, y feed-management:getFeedErrorReport responde 404 para un feed que se procesó correctamente.

El sandbox no está verificado. Walmart emite credenciales de sandbox por separado de las de producción, y nada aquí se ha ejecutado contra sandbox.walmartapis.com. El manejo de WM_SANDBOX: v2, que opta por el sandbox dinámico y cambia la semántica de respuesta en lugar de solo el enrutamiento, se implementa a partir de las especificaciones, no de la observación.

upload_feed no se ha probado de extremo a extremo. Se ejercita con pruebas unitarias contra un transporte con guion únicamente; la única forma de verificarlo en vivo es enviar un feed real, lo que muta un catálogo en vivo. download_file sí se ha verificado contra producción.

La ruta de redirección entre hosts no se ha ejercitado. download_file elimina las credenciales cuando una redirección sale del host de Walmart, lo que importa si un informe se sirve desde almacenamiento firmado. Cada descarga observada hasta ahora devolvió sus bytes directamente, en un solo salto, por lo que esa rama solo tiene cobertura de pruebas unitarias.

Licencia

MIT