mcp-walmart-marketplace

Servidor MCP para APIs do Walmart Marketplace (EUA, vendedor 3P)

Documentação

APIs do Walmart Marketplace

Servidor MCP para APIs do Walmart Marketplace — itens, pedidos, inventário, preços, promoções, feeds, relatórios, devoluções, fulfillment e muito mais.

Expõe descoberta orientada por especificações (list_endpoints, describe_endpoint), um proxy de API genérico (call_endpoint), utilitários de upload de feed e download de arquivos, e um atualizador de especificações em tempo de execução (refresh_specs). O agente de IA descobre endpoints a partir das especificações OpenAPI incluídas e então os chama; o servidor lida automaticamente com a obtenção de tokens OAuth2, renovação e os cabeçalhos obrigatórios do Walmart. Os endereços base são fixados por ambiente, então o arquivo de configuração contém apenas credenciais.

Recursos

Descoberta orientada por especificações — 28 especificações OpenAPI incluídas cobrindo 234 operações, atualizáveis em tempo de execução
Qualquer endpoint — chame por ID de operação ou método+caminho bruto; sem necessidade de alterações de código quando as APIs evoluem
OAuth2 automático — tokens obtidos, armazenados em cache por credencial, renovados antes da expiração, com nova tentativa em caso de 401. O segredo do cliente nunca sai da obtenção de tokens
Multi-anunciante — várias credenciais de vendedor por região e ambiente, selecionadas por chamada
Multi-região, multi-ambiente — produção e sandbox
Cabeçalhos obrigatórios do Walmart (WM_SEC.ACCESS_TOKEN, WM_SVC.NAME, WM_QOS.CORRELATION_ID, WM_MARKET, WM_GLOBAL_VERSION, WM_SANDBOX, WM_PARTNER_ID) injetados no lado do servidor e ocultos do agente
Respostas grandes truncadas com dados completos disponíveis via URI de recurso MCP

Requisitos

Python 3.13+
ID de cliente e segredo de cliente do Walmart Marketplace por vendedor (Portal do Desenvolvedor)

Início rápido

Configure sua configuração (veja Configuração) e então execute o 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

Configuração

O arquivo de configuração fica no diretório inicial do usuário em ~/.config/mcp-walmart-marketplace/config.json.

Nota para Windows: ~ mapeia para %USERPROFILE%, então o caminho completo é %USERPROFILE%\.config\mcp-walmart-marketplace\config.json.

1. Crie o diretório de configuração e copie o exemplo

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

2. Edite ~/.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 configuração	Descrição
`response_cache_ttl`	Segundos para manter respostas truncadas em memória (padrão `3600`)
`truncate_threshold`	Limite de bytes da resposta antes da truncagem (padrão `1024`)
`regions.<R>`	Rótulo da região — sem distinção de maiúsculas/minúsculas, formato livre. Agrupa anunciantes; não altera qual host é chamado
`regions.<R>.<E>`	Ambiente — exatamente `production` ou `sandbox`
`…<E>.credentials[]`	Uma entrada por credencial de cliente Walmart
`…credentials[].client_id`	ID de cliente Walmart (UUID)
`…credentials[].client_secret`	Segredo de cliente Walmart, em texto simples
`…credentials[].advertisers`	Vendedores atendidos por esta credencial, cada `{"id": …}` com um `"partner_id"` opcional

Mantenha o arquivo de configuração legível apenas por você — ele contém segredos de cliente em texto simples.

Todo o resto é fixado pelo servidor: URLs base (marketplace.walmartapis.com para produção, sandbox.walmartapis.com para sandbox), WM_SVC.NAME, a concessão client_credentials e os valores de cabeçalho WM_MARKET / WM_SANDBOX por operação.

Regiões

Uma região é um namespace, não uma rota. Os endereços base são fixados pelo servidor por ambiente, então toda região alcança os mesmos hosts do Walmart. O nível existe para que os IDs de anunciante precisem ser únicos apenas dentro de uma região — o mesmo ID em duas regiões pode significar vendedores diferentes com credenciais diferentes.

IDs de parceiro

Adicione partner_id a um vendedor que tenha um ID de parceiro Walmart:

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

Duas operações payments — payments:getTaxForms e payments:downloadTaxForm — exigem isso como cabeçalho WM_PARTNER_ID. Chamar uma delas para um vendedor configurado sem ID de parceiro falha com uma mensagem informando para adicioná-lo, em vez de um erro 400 do Walmart. Todas as outras operações ignoram isso, então a maioria das entradas é apenas {"id": …}.

Anunciantes

advertiser_id é obrigatório em toda ferramenta que acessa a rede; não há padrão. Leia o recurso wmm://config para descobrir quais IDs de anunciante estão configurados. Ele informa apenas região, ambiente e IDs de anunciante — nunca IDs de cliente ou segredos.

Ferramentas

Ferramenta	Finalidade
`list_endpoints`	Lista operações nas especificações incluídas, filtradas por consulta, domínio, tag ou método
`describe_endpoint`	Uma operação mais seu fechamento de esquema, com cabeçalhos gerenciados pelo servidor removidos
`call_endpoint`	Executa qualquer operação por ID ou método+caminho bruto
`upload_feed`	Envia um arquivo de feed (multipart) para um tipo de feed
`download_file`	Baixa um relatório, etiqueta ou outro binário para um caminho local
`refresh_specs`	Rebusca especificações do registro de API ReadMe para o cache do usuário

Recursos

URI	Conteúdo
`wmm://config`	Regiões, ambientes e IDs de anunciante configurados
`wmm://responses/{request_id}`	Corpo completo de uma resposta truncada
`wmm://curl/{request_id}`	Comando cURL equivalente para uma solicitação anterior

Exemplos de hosts MCP

Cursor

Adicione a .cursor/mcp.json:

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

Claude Code

Adicione à configuração MCP do 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"]
    }
  }
}

Especificações

As 28 especificações incluídas vêm do registro de API ReadMe que sustenta developer.walmart.com. Elas são carregadas primeiro do diretório de cache do usuário (~/.cache/mcp-walmart-marketplace/specs/) e, em caso de falha, da cópia incluída no pacote, então refresh_specs entra em vigor imediatamente sem reinstalação.

Os arquivos em disco são armazenados verbatim como o registro os serviu, então o pacote é a fonte da verdade e um diff de atualização mostra exatamente o que o Walmart mudou. A redução acontece no carregamento, o que a mantém como uma política de tempo de execução em vez de algo embutido nos arquivos:

Exemplos superdimensionados são descartados. Há 3.514 payloads example inline totalizando 4,13 MB, mas a mediana é de 16 bytes e dois payloads /v3/items/taxonomy respondem por 3,25 MB. Tudo em ou abaixo de MAX_EXAMPLE_BYTES (1 KB) sobrevive — 97% deles, cerca de 133 KB — então dicas de formato para datas, SKUs e identificadores permanecem disponíveis enquanto os gigantes nunca chegam a um agente.
x-readme é removido — metadados de renderização da plataforma de documentação, não detalhes de API.

O custo de carregar todas as 28 especificações é de ~80 ms uma vez por processo; os resultados são armazenados em cache por especificação e invalidados pelo mtime do arquivo, então um refresh_specs entra em vigor imediatamente. A saída de describe_endpoint é de 5,1 KB na mediana e 88 KB no pior caso (seis operações order-management inline com esquemas de resposta muito grandes).

Para reconstruir as cópias incluídas:

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

Advertências

As especificações e a API discordam sobre autenticação. 76 operações declaram um cabeçalho Authorization Basic construído a partir do ID e segredo do cliente, e fulfillment-management e insights-management parecem exigi-lo em vez de um token de acesso. Testado contra produção, isso está errado: apenas Basic retorna 401, apenas o token de acesso retorna 200, em todos os serviços testados. Este servidor, portanto, envia WM_SEC.ACCESS_TOKEN em toda solicitação e nunca envia o segredo do cliente em nenhum lugar exceto /v3/token. Se você comparar seu comportamento com os documentos de referência, essa lacuna é deliberada.

WM_SVC.NAME não pode ser lido das especificações. 103 operações declaram a string literal de espaço reservado "Walmart Service Name" e apenas 100 o valor real, então ele é fixado em Walmart Marketplace, o que chamadas reais confirmam.

Nem todo endpoint documentado é acessível com credenciais de vendedor. GET /v3/utilities/apiStatus retorna HTTP 520 Unable to route request, nomeando wm_svc.name: PARTNERMANAGEMENTSERVICES e wm_svc.env: prod como os cabeçalhos esperados — mas enviar exatamente esses ainda retorna 520. Parece pertencer a um serviço que credenciais 3P não conseguem acessar, e a mensagem de erro é uma pista falsa. Espere um punhado de casos semelhantes entre 234 operações.

Endpoints de relatório negociam conteúdo estritamente. Eles rejeitam Accept: */* com um 406 listando o que podem produzir, então Accept é derivado dos tipos de mídia que a operação declara para suas respostas de sucesso (preferindo application/json quando oferecido). Se você adicionar um endpoint cuja especificação não declara conteúdo de resposta, ele recai para */* e pode retornar 406.

A cobertura ao vivo é limitada. Sete operações em cinco domínios retornaram 200 contra produção — feed-management, advertising, fulfillment-management, insights-management, settings-management — incluindo dois downloads de relatório que chegam como pastas de trabalho Excel reais. As outras ~227 são conectadas a partir das especificações e nunca foram chamadas. Descoberta e construção de solicitações são cobertas por testes; o comportamento upstream não é.

Duas falhas upstream conhecidas, nenhuma delas bug do cliente: fulfillment-management:getInventoryHealthReport responde 520 WFS_INTERNAL_SERVER_ERROR, e feed-management:getFeedErrorReport responde 404 para um feed que foi processado corretamente.

Sandbox não é verificado. O Walmart emite credenciais de sandbox separadamente da produção, e nada aqui foi executado contra sandbox.walmartapis.com. O tratamento de WM_SANDBOX: v2 — que opta pelo sandbox dinâmico e muda a semântica de resposta em vez de apenas roteamento — é implementado a partir das especificações, não observado.

upload_feed não é testado de ponta a ponta. É exercitado por testes de unidade apenas contra um transporte com script — a única maneira de verificá-lo ao vivo é enviar um feed real, o que altera um catálogo ao vivo. download_file foi verificado contra produção.

O caminho de redirecionamento entre hosts não é exercitado. download_file remove credenciais quando um redirecionamento sai do host do Walmart, o que importa se um relatório for servido de armazenamento assinado. Cada download observado até agora retornou seus bytes diretamente, em um salto, então esse ramo tem apenas cobertura de teste de unidade.

Licença

MIT