Walmart Marketplace MCP 服务器

用于 Walmart Marketplace APIs 的 MCP 服务器——涵盖商品、订单、库存、价格、促销、馈送、报告、退货、履约等。

提供基于规范的发现功能（list_endpoints、describe_endpoint）、通用 API 代理（call_endpoint）、馈送上传和文件下载辅助工具，以及运行时规范刷新器（refresh_specs）。AI 代理从内置的 OpenAPI 规范中发现端点，然后调用它们；服务器自动处理 OAuth2 令牌获取、刷新以及 Walmart 要求的请求头。基础地址按环境硬编码，因此配置文件只包含凭证。

功能特性

• 基于规范的发现 — 28 份内置 OpenAPI 规范，覆盖 234 个操作，可在运行时刷新

• 任意端点 — 按操作 ID 或原始方法+路径调用；API 演进时无需修改代码

• 自动 OAuth2 — 按凭证缓存令牌，过期前自动刷新，遇到 401 自动重试一次。客户端密钥绝不会离开令牌获取环节

• 多广告主 — 每个区域和环境可配置多个卖家凭证，按调用选择

• 多区域、多环境 — 支持生产环境和沙箱环境

• 必需的 Walmart 请求头（WM_SEC.ACCESS_TOKEN、WM_SVC.NAME、WM_QOS.CORRELATION_ID、WM_MARKET、WM_GLOBAL_VERSION、WM_SANDBOX、WM_PARTNER_ID）由服务器端注入，对代理隐藏

• 大型响应会被截断，完整数据可通过 MCP 资源 URI 获取

Related MCP server: MoySklad MCP Server

环境要求

• Python 3.13+

• 每个卖家需要 Walmart Marketplace 客户端 ID 和客户端密钥（开发者门户）

快速开始

配置好你的配置文件（参见配置），然后运行服务器：

# 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 }]
          }
        ]
      }
    }
  }
}

配置文件只能由你本人可读——其中包含明文客户端密钥。

其他一切均由服务器固定：基础地址（生产环境为 marketplace.walmartapis.com，沙箱为 sandbox.walmartapis.com）、WM_SVC.NAME、client_credentials 授权类型，以及每个操作的 WM_MARKET / WM_SANDBOX 请求头值。

区域

区域是命名空间，不是路由。基础地址由服务器按环境固定，因此每个区域访问的是相同的 Walmart 主机。区域的作用是让广告主 ID 只需在单个区域内唯一——同一个 ID 在不同区域下可以对应不同的卖家，使用不同的凭证。

合作伙伴 ID

为具有 Walmart 合作伙伴 ID 的卖家添加 partner_id：

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

两个 payments 操作——payments:getTaxForms 和 payments:downloadTaxForm——需要将其作为 WM_PARTNER_ID 请求头。如果为未配置合作伙伴 ID 的卖家调用这些操作，会返回一条提示你添加该字段的错误消息，而不是 Walmart 的 400 错误。其他所有操作都会忽略该字段，因此大多数条目只需 {"id": …}。

广告主

advertiser_id 是所有需要访问网络的工具的必填参数；没有默认值。读取 wmm://config 资源可以查看已配置了哪些广告主 ID。该资源只报告区域、环境和广告主 ID——绝不会暴露客户端 ID 或密钥。

工具

资源

MCP 主机示例

Cursor

添加到 .cursor/mcp.json：

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

Claude Code

添加到你的 Claude Code MCP 配置：

{
  "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 份规范来自支撑 developer.walmart.com 的 ReadMe api-registry。它们首先从用户缓存目录加载（~/.cache/mcp-walmart-marketplace/specs/），如果不存在则回退到随 wheel 包附带的副本，因此 refresh_specs 无需重新安装即可立即生效。

磁盘上的文件原样存储了注册表提供的原始内容，因此内置副本是事实来源，刷新后的差异可以精确显示 Walmart 的变更内容。缩减处理在加载时进行，这是一种运行时策略，而非写入文件的内容：

• 过大的示例会被丢弃。 共有 3,514 个内联 example 负载，总计 4.13 MB，但中位数仅为 16 字节，而两个 /v3/items/taxonomy 负载就占了 3.25 MB。所有不超过 MAX_EXAMPLE_BYTES（1 KB）的示例都会保留——占总数 97%，约 133 KB——因此日期、SKU 和标识符的格式提示仍然可用，而那些庞然大物永远不会到达代理。

• x-readme 会被移除——这是文档平台的渲染元数据，不是 API 细节。

加载全部 28 份规范的开销约为每个进程一次 80 毫秒；结果按规范缓存，并通过文件修改时间失效，因此 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 个操作声明了基于客户端 ID 和密钥构建的 Basic Authorization 请求头，而 fulfillment-management 和 insights-management 似乎要求使用它而不是访问令牌。针对生产环境的探测表明这是错误的：仅使用 Basic 会返回 401，仅使用访问令牌会返回 200，在所有测试过的服务上都是如此。因此，此服务器在每个请求上都发送 WM_SEC.ACCESS_TOKEN，并且除了 /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 个操作中，预计还会有少量类似情况。

报告端点对内容协商有严格要求。 它们会以 406 拒绝 Accept: */*，并列出可以生成的内容类型，因此 Accept 是根据操作为其成功响应声明的媒体类型推导的（在提供 application/json 时优先选择）。如果你添加的端点在规范中未声明任何响应内容，则会回退到 */*，可能返回 406。

实时覆盖有限。 已有七个跨五个域的操作对生产环境返回了 200——feed-management、advertising、fulfillment-management、insights-management、settings-management——其中包括两个以真实 Excel 工作簿形式到达的报告下载。其余约 227 个操作是根据规范接线的，从未被实际调用过。发现和请求构造有测试覆盖；上游行为则没有。

两个已知的上游故障，均非客户端缺陷：fulfillment-management:getInventoryHealthReport 返回 520 WFS_INTERNAL_SERVER_ERROR，以及 feed-management:getFeedErrorReport 对处理正常的馈送返回 404。

沙箱环境未经验证。 Walmart 单独发放沙箱凭证，与生产环境凭证不同，而且这里没有任何内容在 sandbox.walmartapis.com 上运行过。WM_SANDBOX: v2 的处理——它选择动态沙箱并改变响应语义，而不仅仅是路由——是根据规范实现的，并非实际观察所得。

upload_feed 未经端到端测试。 它仅通过单元测试针对脚本化传输进行了验证——唯一能实时验证它的方式是提交真实馈送，而这会修改真实目录。download_file 已经在生产环境中验证过。

跨主机重定向路径未经实际演练。 当重定向离开 Walmart 的主机时，download_file 会丢弃凭证，如果报告从签名存储提供，这一点很重要。目前观察到的所有下载都是单跳直接返回字节，因此该分支只有单元测试覆盖。

许可证

MIT