Sam's Club Sponsored Ads APIs (deprecated)

Walmart 和 Sam's Club API

一个 MCP 服务，通过统一的工具接口提供 Walmart Inc. 三类 API：

四个工具，覆盖 31 个 API 和 424 个操作——包括发现、通用代理和下载器。Agent 可在捆绑的 OpenAPI 规范中查找端点并调用它们；服务负责签名、获取令牌并构建标头。

walmart:ads:sponsored-products:SBAProfileUpdateV2
└─ retailer ─┘└ line ┘└─── api name ───┘└── operationId ──┘
   └────────── platform ─────────┘  credentials attach here

仅凭操作 ID 即可确定主机和身份验证模式。匹配的 <line>:<name> 后缀表示同一接口也适用于其他零售商——90 个操作 ID 中有 13 个共享。

要求

• Python 3.13+
• 你所使用平台的凭据。只配置需要的平台——未配置的平台会被视为未配置状态；即使完全没有凭据，也可以使用发现功能。
  • Walmart Connect / Sam's Club — consumer ID、RSA 密钥对、bearer token
  • Walmart Marketplace — client ID 和 secret，以及它们服务的广告主（卖家资料）ID

快速开始

设置配置（参见配置），然后运行服务：

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

# Or run from source
git clone https://github.com/alyiox/mcp-walmart-ads.git
cd mcp-walmart-ads
uv sync
npx -y @modelcontextprotocol/inspector@latest uv run mcp-walmart-ads

配置

config.json 必须位于 ~/.config/mcp-walmart-ads/config.json。服务只会在启动时读取一次，因此修正文件后必须重启。

Windows： ~ 对应 %USERPROFILE%（通常为 C:\Users\<you>），完整路径为 %USERPROFILE%\.config\mcp-walmart-ads\config.json。

创建目录并复制示例：

# Unix-like (macOS, Linux, WSL, …)
mkdir -p ~/.config/mcp-walmart-ads/keys/walmart-ads
cp config.example.json ~/.config/mcp-walmart-ads/config.json

# Windows (PowerShell)
New-Item -ItemType Directory -Force "$env:USERPROFILE\.config\mcp-walmart-ads\keys\walmart-ads"
Copy-Item config.example.json "$env:USERPROFILE\.config\mcp-walmart-ads\config.json"

结构

platforms.<platform>.regions.<region>.<environment> = <auth block>

<platform> 是 API ID 开头的两段式前缀，因此配置键就是你作为 platform 工具参数传入的值，无需翻译。

认证块的结构遵循平台的认证模型。每个平台只有一种结构，因此无需判别字段。

签名平台（walmart:ads、samsclub:ads）：

{
  "platforms": {
    "walmart:ads": {
      "regions": {
        "us": {
          "production": {
            "consumer_id": "your-consumer-id",
            "private_key": "./keys/walmart-ads/us-prod.pem",
            "private_key_version": "1",
            "bearer_token": "your-bearer-token",
            "base_urls": {
              "sponsored-products": "https://developer.api.walmart.com/api-proxy/service/WPA/Api/v1",
              "display": "https://developer.api.walmart.com/api-proxy/service/display/api/v1"
            }
          }
        }
      }
    }
  }
}

此处的环境名称可以自由设置——Walmart 可能只为某个租户提供 production，也可能提供 production 和 staging。

OAuth2 平台（walmart:marketplace）：

{
  "platforms": {
    "walmart:marketplace": {
      "regions": {
        "us": {
          "production": {
            "credentials": [
              {
                "client_id": "your-client-id",
                "client_secret": "your-client-secret",
                "advertisers": [
                  { "id": 7060158, "partner_id": "10001234" },
                  { "id": 7060159 }
                ]
              }
            ]
          }
        }
      }
    }
  }
}

environment 必须是 production 或 sandbox；基础 URL 由服务固定，不在文件中提供。广告主 ID 嵌套在为其提供服务的凭据下，因此密钥只会出现一次，也不可能在结构上出现无效的广告主引用。partner_id 按卖家设置，因为两个 payments 操作需要将其作为 WM_PARTNER_ID；全零值会被视为缺失，因为生成的配置会为没有该值的卖家写入全零值，而 scripts/backfill_partner_ids.py 会从 Walmart 补齐缺失值。

区域是命名空间，而非路由——每个 walmart:marketplace 区域都会访问相同的主机。设置这一层级是因为广告主 ID 仅在区域内唯一。

拆分配置

已填充的 walmart:marketplace 块会包含数十 KB 的凭据，占此处文件内容的 88%；编辑时多出一个逗号就会导致所有平台不可用：配置解析失败会先于逐个平台的验证。因此，平台可以放在 config.d/ 下的独立文件中，并与基础配置合并：

~/.config/mcp-walmart-ads/
├── config.json                  # server-wide settings, and any platforms you like
├── config.d/
│   ├── walmart-marketplace.json # only a "platforms" object
│   └── samsclub-ads.json
└── keys/

• 独立配置文件必须只声明 platforms；服务器级设置仍应放在 config.json 中。
• 如果在两个文件中声明了同一平台，必须报错并指出这两个文件，绝不能静默决定优先级。
• 只会读取 config.d/ 目录下的 *.json 文件，因此会忽略 .bak 和编辑器交换文件。
• 如果某个文件解析失败，只影响该文件中的平台；其余平台仍可正常工作。
• 无论如何，相对 private_key 路径都以 config.json 所在目录为基准解析，因此将平台移入 config.d/ 无需修改路径。
• 没有 config.d/ 目录时，行为不会改变。

某个平台的配置块格式错误，不得阻止其他平台加载。读取 wmt://platforms，即可查看哪些平台已加载，以及它们声明了哪些区域和环境：加载失败的平台没有区域；读取其某个环境时会返回加载器自身的错误信息，指出涉及的文件和字段，并说明修复后需要重启。

顶层选项

市场 → 租户（wap-tenant-id）

对于非美国的 walmart:ads 市场（WMT_CA、WMT_MX、WBD_OD 等），在 call_endpoint 和 download_file 中传入 tenant。美国市场和 walmart:marketplace 则省略此参数。

工具

list_endpoints

列出所有 API 中的操作，并支持可选筛选条件。

返回的操作 ID 带有完整限定符（api:operationId），可直接传给 describe_endpoint 或 call_endpoint。

describe_endpoint

返回一个操作及其可访问的所有 components.schemas 条目，因此无需完整规范即可构建请求正文。省略由服务端管理的身份验证和 QoS 标头。

call_endpoint

向任何已配置的平台发送经过身份验证的请求。签名、按凭据缓存并通过 single-flight 刷新获取令牌，以及在收到 401 后重试一次，均由服务端处理。

如果响应大于 truncate_threshold，则会以内联预览形式返回；完整正文位于 wmt://responses/{request_id}，可复现的 cURL 命令位于 wmt://curl/{request_id} — bearer 令牌、访问令牌和签名会替换为占位符。

download_file

从经过身份验证的端点下载报告、标签或快照。提供完整的 url（例如显示快照轮询返回的 details URL），或提供 operation_id，或提供 api 以及 method + path。仅当 url 不带限定符时才需要 platform。

提供 dest_path 时，字节数据会写入该路径。未提供时，若文件经过 gzip 压缩，则会先解压再缓存，结果中会包含 cached_at — 未提供 dest_path 的二进制负载会要求提供一个路径。跟随重定向时，如果 Location 为相对地址或同主机地址，则保留身份验证标头；跨主机时则移除凭据。结果中会包含表示跳转路径的 urls。

规范

此 wheel 中包含 33 份 OpenAPI 文档。刷新时会将更新后的副本写入 ~/.cache/mcp-walmart-ads/specs/；读取时此目录的优先级高于捆绑包。运行时绝不会写入捆绑包，因此当缓存损坏或缺失时，它仍可作为回退基础。

它们的来源

Walmart 不发布 OpenAPI 文件，但每个 ReadMe 参考页面都会在其 HTML 中填充文档的注册表 UUID，而 https://dash.readme.com/api/v1/api-registry/<uuid> 无需身份验证即可提供完整规范。这涵盖 Walmart Connect 和全部 28 个 Marketplace 域名。Sam's Club 两者都不发布，因此其规范根据开发者文档手工编写：scripts/build_samsclub_spec.py 会根据这些文档重新生成一个候选版本；文档发生变化时，定时运行的 spec drift 工作流会创建 PR，作为人工审核关卡。候选版本不会发布，也不会在运行时加载。

文档会按照上游提供的原样存储，因此刷新时的差异会准确显示发生了哪些变化。加载时会剥除过大的内联示例和 x-readme 元数据，而不是在磁盘上剥除，这样无需重新下载即可调整精简方式。

保持最新

规范会在后台刷新：启动时刷新一次，之后每隔 spec_refresh.interval 天刷新一次（默认为 7 天）。将 auto 设为 false 可停止定期刷新；该间隔会保留，供你重新启用时使用，手动刷新仍然可用。

如果你已遇到捆绑规范中没有的端点，现在即可刷新：

# Installed with uvx (no clone)
uvx mcp-walmart-ads --refresh

# Or from a source checkout
uv run mcp-walmart-ads --refresh

两种形式都会忽略间隔设置，刷新所有规范并写入同一用户缓存；每份文档会打印一行状态：written、unchanged 或 error。

这里有意不提供用于此操作的工具。在会话中，无法区分过时规范和最新规范——它只会缺少某个端点——因此，如果让 Agent 来决定，它要么永远不刷新，要么在遇到无关故障后凭直觉刷新。触发刷新应当发生在会话之外。

文档必须至少包含一个操作才能安装，这样上游即使以 200 状态返回错误正文，也不会污染缓存；内容完全相同的文档则不会被改动。无法加载的缓存文件会被丢弃，读取操作将回退到捆绑版本。各服务通过缓存根目录中的 spec-state.json 协调，该文件记录每份规范最近一次尝试的时间，并持有租约，确保同一时间只有一个进程执行刷新——每个客户端会话都会运行自己的服务进程；没有该机制时，每个进程都会重新下载全部 33 份规范。

重新构建捆绑版本

这是维护者执行的步骤，与 --refresh 不同：后者更新你的缓存，此步骤更新随 wheel 一同发布的副本。

# Registry-sourced specs only, by default
uv run python scripts/fetch_specs.py
uv run python scripts/fetch_specs.py walmart:ads:sponsored-products walmart:marketplace:order-management

# Regenerate the Sam's Club candidate spec for review
uv run --group spec-build python scripts/build_samsclub_spec.py

MCP 资源

MCP 宿主示例

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

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

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

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

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

开发

uv sync --group dev
uv run ruff check src/ tests/ scripts/
uv run ruff format --check src/ tests/ scripts/
uv run pyright
uv run pytest tests/ -v

贡献

欢迎提交问题和拉取请求。请保持更改聚焦；ruff check、ruff format --check、pyright 和 pytest 必须全部通过。

许可证

LICENSE。