Walmart Marketplace APIs

Walmart Marketplace APIs 用の MCP サーバー — 商品、注文、在庫、価格、プロモーション、フィード、レポート、返品、フルフィルメントなど。

仕様駆動のディスカバリ（list_endpoints、describe_endpoint）、汎用 API プロキシ（call_endpoint）、フィードアップロードとファイルダウンロードのヘルパー、および実行時仕様リフレッシャー（refresh_specs）を公開します。AI エージェントはバンドルされた OpenAPI 仕様からエンドポイントを発見して呼び出します。サーバーは OAuth2 トークンの取得、更新、および Walmart の必須ヘッダーを自動的に処理します。ベースアドレスは環境ごとにハードコードされているため、設定ファイルには認証情報以外は何も含まれません。

Features

• 仕様駆動のディスカバリ — バンドルされた 28 の OpenAPI 仕様が 234 の操作をカバーし、実行時に更新可能

• 任意のエンドポイント — 操作 ID または生のメソッド+パスで呼び出し。API が進化してもコード変更は不要

• 自動 OAuth2 — トークンは資格情報ごとに取得・キャッシュされ、期限前に更新され、401 の場合は 1 回再試行されます。クライアントシークレットはトークン取得の場から決して出ません

• マルチアドバタイザー — リージョンと環境ごとに複数のセラー資格情報を持ち、呼び出しごとに選択

• マルチリージョン、マルチ環境 — 本番とサンドボックス

• 必須の 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

Requirements

• Python 3.13+

• Walmart Marketplace クライアント ID とクライアントシークレットをセラーごとに（Developer Portal）

Quick start

設定（設定を参照）を行い、サーバーを実行します：

# 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

Configuration

設定ファイルはホームディレクトリの ~/.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、サンドボックスは sandbox.walmartapis.com）、WM_SVC.NAME、client_credentials グラント、および操作ごとの WM_MARKET / WM_SANDBOX ヘッダー値。

Regions

リージョンは名前空間であり、ルートではありません。ベースアドレスは環境ごとにサーバーで固定されているため、すべてのリージョンが同じ Walmart ホストに到達します。この階層があるのは、アドバタイザー ID が 1 つのリージョン内で一意であればよいようにするためです — 2 つのリージョンにある同じ ID は、異なる資格情報を持つ異なるセラーを意味することがあります。

Partner IDs

Walmart パートナー ID を持つセラーに partner_id を追加します：

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

2 つの payments 操作 — payments:getTaxForms と payments:downloadTaxForm — は、WM_PARTNER_ID ヘッダーとしてこれを必要とします。パートナー ID なしで設定されたセラーに対してこれらを呼び出すと、Walmart の 400 ではなく、追加を促すメッセージで失敗します。他のすべての操作はこれを無視するため、ほとんどのエントリは単に {"id": …} です。

Advertisers

advertiser_id はネットワークに到達するすべてのツールで必須であり、デフォルトはありません。wmm://config リソースを読むと、どのアドバタイザー ID が設定されているかを確認できます。リージョン、環境、アドバタイザー ID のみが報告され、クライアント ID やシークレットは決して報告されません。

Tools

Resources

MCP host examples

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

Specs

バンドルされた 28 の仕様は、developer.walmart.com を支える ReadMe api-registry から取得されています。これらはまずユーザーキャッシュディレクトリ（~/.cache/mcp-walmart-marketplace/specs/）から読み込まれ、wheel に同梱されたコピーにフォールバックするため、refresh_specs は再インストールなしで即座に反映されます。

ディスク上のファイルは、レジストリが提供したまま逐語的に保存されるため、バンドルが信頼できる情報源となり、更新時の差分には Walmart が変更した内容が正確に表示されます。削減は読み込み時に行われるため、ファイルに焼き込まれるのではなく、実行時ポリシーとして維持されます：

• 過大なサンプルは削除されます。 インラインの example ペイロードは 3,514 件、合計 4.13 MB ありますが、中央値は 16 バイトで、2 つの /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 です（6 つの order-management 操作が非常に大きなレスポンススキーマをインライン展開します）。

バンドルされたコピーを再構築するには：

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

Caveats

仕様と 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 の操作の中に同様のケースがいくつかあると想定してください。

レポートエンドポイントはコンテンツ交渉を厳格に行います。 これらは Accept: */* を 406 で拒否し、生成可能なものを列挙するため、Accept は操作が成功レスポンスとして宣言するメディアタイプから導出されます（提供される場合は application/json を優先）。レスポンスコンテンツを宣言しない仕様のエンドポイントを追加した場合、*/* にフォールバックし、406 になる可能性があります。

実環境でのカバレッジは薄いです。 5 つのドメインにわたる 7 つの操作が本番に対して 200 を返したことがあります — feed-management、advertising、fulfillment-management、insights-management、settings-management — 実際の Excel ワークブックとして届く 2 つのレポートダウンロードを含みます。他の約 227 は仕様から配線されただけで、呼び出されたことはありません。ディスカバリとリクエスト構築はテストでカバーされていますが、上流の動作はカバーされていません。

既知の上流障害が 2 つあり、どちらもクライアントのバグではありません：fulfillment-management:getInventoryHealthReport は 520 WFS_INTERNAL_SERVER_ERROR を返し、feed-management:getFeedErrorReport は正常に処理されたフィードに対して 404 を返します。

サンドボックスは未検証です。 Walmart はサンドボックス資格情報を本番とは別に発行しており、ここでは sandbox.walmartapis.com に対して何も実行されていません。WM_SANDBOX: v2 の処理 — これは動的サンドボックスを選択し、ルーティングだけでなくレスポンスの意味も変更します — は仕様から実装されたものであり、観測されたものではありません。

upload_feed はエンドツーエンドで未テストです。 これはスクリプト化されたトランスポートに対するユニットテストでのみ実行されています — 実環境で検証する唯一の方法は実際のフィードを送信することであり、それは実在のカタログを変更します。download_file は本番に対して検証済みです。

クロスホストリダイレクトの経路は未実行です。 download_file はリダイレクトが Walmart のホストから離れると資格情報を破棄します。これは、レポートが署名付きストレージから提供される場合に重要です。これまでに観測されたすべてのダウンロードは、1 ホップで直接バイトを返したため、その分岐はユニットテストのカバレッジのみです。

License

MIT