Walmart Marketplace APIs

MCP-сервер для Walmart Marketplace APIs — товары, заказы, остатки, цены, акции, фиды, отчёты, возвраты, логистика и другое.

Предоставляет управляемое спецификациями обнаружение (list_endpoints, describe_endpoint), универсальный API-прокси (call_endpoint), помощники для загрузки фидов и скачивания файлов, а также обновление спецификаций в рантайме (refresh_specs). ИИ-агент обнаруживает эндпоинты во встроенных OpenAPI-спецификациях, а затем вызывает их; сервер автоматически обрабатывает получение и обновление OAuth2-токенов и обязательные заголовки Walmart. Базовые адреса жёстко заданы для каждого окружения, поэтому в конфигурационном файле хранятся только учётные данные.

Возможности

• Обнаружение на основе спецификаций — 28 встроенных OpenAPI-спецификаций, покрывающих 234 операции, обновляемые в рантайме

• Любой эндпоинт — вызов по идентификатору операции или по паре метод+путь; при изменении API не требуется правок кода

• Автоматический OAuth2 — токены получаются, кэшируются для каждого набора учётных данных, обновляются до истечения срока, при 401 выполняется одна повторная попытка. Секрет клиента никогда не покидает этап получения токена

• Несколько продавцов — много учётных данных продавца для каждого региона и окружения, выбор при каждом вызове

• Мультирегиональность и мультиокружение — production и sandbox

• Обязательные заголовки Walmart (WM_SEC.ACCESS_TOKEN, WM_SVC.NAME, WM_QOS.CORRELATION_ID, WM_MARKET, WM_GLOBAL_VERSION, WM_SANDBOX, WM_PARTNER_ID) внедряются на стороне сервера и скрыты от агента

• Большие ответы усекаются, полные данные доступны через URI ресурса MCP

Related MCP server: MoySklad MCP Server

Требования

• Python 3.13+

• Walmart Marketplace client ID и client secret для каждого продавца (Developer Portal)

Быстрый старт

Настройте конфигурацию (см. Конфигурация), затем запустите сервер:

# 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

Конфигурация

Конфигурационный файл находится в вашем домашнем каталоге по пути ~/.config/mcp-walmart-marketplace/config.json.

Примечание для Windows: ~ соответствует %USERPROFILE%, поэтому полный путь — %USERPROFILE%\.config\mcp-walmart-marketplace\config.json.

1. Создайте каталог конфигурации и скопируйте пример

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

2. Отредактируйте ~/.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 }]
          }
        ]
      }
    }
  }
}

Сделайте конфигурационный файл доступным для чтения только вам — в нём хранятся секреты клиентов в открытом виде.

Всё остальное фиксировано сервером: базовые URL (marketplace.walmartapis.com для production, sandbox.walmartapis.com для sandbox), WM_SVC.NAME, грант client_credentials и значения заголовков WM_MARKET / WM_SANDBOX для каждой операции.

Регионы

Регион — это пространство имён, а не маршрут. Базовые адреса фиксированы сервером для каждого окружения, поэтому любой регион обращается к одним и тем же хостам Walmart. Этот уровень нужен, чтобы advertiser id были уникальны только в пределах одного региона — один и тот же id в двух регионах может означать разных продавцов с разными учётными данными.

Partner ID

Добавьте partner_id продавцу, у которого есть Walmart Partner ID:

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

Две операции payments — payments:getTaxForms и payments:downloadTaxForm — требуют его в заголовке WM_PARTNER_ID. Вызов такой операции для продавца, настроенного без partner id, завершится ошибкой с сообщением о необходимости добавить его, а не Walmart 400. Все остальные операции игнорируют его, поэтому большинство записей — просто {"id": …}.

Продавцы

advertiser_id обязателен для каждого инструмента, который обращается к сети; значения по умолчанию нет. Прочитайте ресурс wmm://config, чтобы узнать, какие advertiser id настроены. Он сообщает только регион, окружение и advertiser id — никогда client id или секреты.

Инструменты

Ресурсы

Примеры MCP-хостов

Cursor

Добавьте в .cursor/mcp.json:

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

Claude Code

Добавьте в конфигурацию MCP для 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"]
    }
  }
}

Спецификации

28 встроенных спецификаций взяты из ReadMe api-registry, который лежит в основе developer.walmart.com. Они сначала загружаются из пользовательского каталога кэша (~/.cache/mcp-walmart-marketplace/specs/), а при отсутствии — из копии, поставляемой в wheel, поэтому refresh_specs вступает в силу немедленно, без переустановки.

Файлы на диске хранятся дословно в том виде, в котором их отдал реестр, поэтому комплект является источником истины, а diff после обновления показывает ровно то, что изменил Walmart. Сокращение происходит при загрузке, что делает его политикой времени выполнения, а не чем-то, зашитым в файлы:

• Слишком большие примеры отбрасываются. Всего есть 3,514 встроенных example-полезных нагрузок общим объёмом 4.13 MB, но медиана — 16 bytes, а две нагрузки /v3/items/taxonomy занимают 3.25 MB. Всё, что не превышает MAX_EXAMPLE_BYTES (1 KB), сохраняется — 97% из них, для ~133 KB, — так что подсказки по форматам дат, sku и идентификаторов остаются доступны, а «монстры» никогда не попадают к агенту.

• x-readme удаляется — это метаданные рендеринга документационной платформы, а не детали API.

Загрузка всех 28 спецификаций стоит ~80 ms один раз на процесс; результаты кэшируются для каждой спецификации и инвалидируются по mtime файла, поэтому refresh_specs вступает в силу немедленно. Вывод describe_endpoint имеет медианный размер 5.1 KB и максимальный 88 KB (шесть операций order-management включают очень большие схемы ответов).

Чтобы пересобрать встроенные копии:

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

Предостережения

Спецификации и API расходятся в вопросе аутентификации. 76 операций объявляют заголовок Basic Authorization, формируемый из client id и секрета, а fulfillment-management и insights-management, судя по всему, требуют его вместо токена доступа. Проверка на production показывает, что это не так: на каждом протестированном сервисе один Basic возвращает 401, а один токен доступа — 200. Поэтому этот сервер отправляет WM_SEC.ACCESS_TOKEN в каждом запросе и никогда не отправляет client secret никуда, кроме /v3/token. Если вы сравните его поведение со справочной документацией, это расхождение намеренно.

WM_SVC.NAME нельзя прочитать из спецификаций. 103 операции объявляют буквальную строку-заглушку "Walmart Service Name" и только 100 — реальное значение, поэтому оно зафиксировано как Walmart Marketplace, что подтверждают реальные вызовы.

Не каждый документированный эндпоинт доступен с учётными данными продавца. GET /v3/utilities/apiStatus возвращает HTTP 520 Unable to route request, указывая wm_svc.name: PARTNERMANAGEMENTSERVICES и wm_svc.env: prod как ожидаемые заголовки, но отправка именно их по-прежнему даёт 520. Похоже, он принадлежит сервису, недоступному для 3P-учётных данных, а сообщение об ошибке вводит в заблуждение. Ожидайте несколько похожих случаев среди 234 операций.

Эндпоинты отчётов строго согласуют содержимое. Они отклоняют Accept: */* с кодом 406 и перечнем того, что могут выдать, поэтому Accept выводится из типов медиа, объявленных операцией для успешных ответов (с предпочтением application/json, если он предлагается). Если вы добавите эндпоинт, в спецификации которого не объявлено содержимое ответа, он вернётся к */* и может ответить 406.

Покрытие реальными вызовами невелико. Семь операций из пяти доменов вернули 200 на production — feed-management, advertising, fulfillment-management, insights-management, settings-management — включая две загрузки отчётов, которые приходят как настоящие книги Excel. Остальные ~227 подключены на основе спецификаций и ни разу не вызывались. Обнаружение и формирование запросов покрыты тестами; поведение вышестоящей системы — нет.

Два известных сбоя вышестоящей системы, ни один из которых не является ошибкой клиента: fulfillment-management:getInventoryHealthReport отвечает 520 WFS_INTERNAL_SERVER_ERROR, а feed-management:getFeedErrorReport отвечает 404 для фида, который обработался без ошибок.

Sandbox не проверен. Walmart выдаёт sandbox-учётные данные отдельно от production, и ничего здесь не запускалось против sandbox.walmartapis.com. Обработка WM_SANDBOX: v2 — которая включает динамический sandbox и меняет семантику ответов, а не только маршрутизацию — реализована по спецификациям, а не по наблюдениям.

upload_feed не протестирован сквозным образом. Он проверяется только модульными тестами против скриптованного транспорта — единственный способ проверить его вживую — отправить настоящий фид, что изменяет живой каталог. download_file был проверен на production.

Путь редиректа между хостами не опробован. download_file сбрасывает учётные данные, когда редирект уводит с хоста Walmart, что важно, если отчёт когда-либо будет отдаваться из подписанного хранилища. Все наблюдавшиеся до сих пор загрузки возвращали байты напрямую, за один переход, поэтому эта ветвь покрыта только модульными тестами.

Лицензия

MIT