Sam's Club Sponsored Ads APIs (deprecated)

Walmart & Sam's Club API

3つのWalmart Inc. APIファミリーに対応するMCP サーバーです。1つのツールインターフェースから利用できます。

31個のAPIと424個の操作に対応する4つのツールを提供します。ディスカバリー、汎用プロキシ、ダウンローダーを備えています。エージェントは同梱の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 — コンシューマーID、RSAキーペア、ベアラートークン
  • Walmart Marketplace — クライアントIDとシークレット、およびそれらが対応する広告主（販売者プロフィール）の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 が始まる 2 セグメントのプレフィックスです。そのため、設定キーには platform ツールパラメーターに渡す値をそのまま指定します。翻訳は不要です。

認証ブロックの形状は、プラットフォームの認証モデルに従います。プラットフォームごとに形状は 1 つだけなので、識別子フィールドは不要です。

署名認証プラットフォーム（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 は、それを提供する認証情報の下にネストされるため、 シークレットは 1 回だけ記述され、参照先のない広告主 ID が構造上発生することはありません。partner_id は販売者ごとに指定します。payments の 2 つの操作で WM_PARTNER_ID として必要になるためです。 すべてゼロの値は未設定として扱われます。これは、該当する ID を持たない販売者用に生成された設定が 書き込む値であり、scripts/backfill_partner_ids.py が Walmart から不足分を補完します。

リージョンは名前空間であり、ルートではありません。すべての walmart:marketplace リージョンは同じ ホストにアクセスします。この階層が存在するのは、広告主 ID がリージョン内でのみ一意だからです。

設定の分割

設定済みの walmart:marketplace ブロックは、認証情報だけで数十キロバイトに達し、このファイルの 88% を 占めます。また、編集中に余計なカンマが 1 つ入るだけで、プラットフォームごとの検証より前に 解析エラーが発生し、すべてのプラットフォームが停止します。そのため、プラットフォームは 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 に記述します。
• 2 つのファイルで同じプラットフォームが宣言されている場合、両方のファイル名を示すエラーになります。優先順位によって黙って上書きされることはありません。
• config.d/ 直下にある *.json のみが読み込まれるため、.bak ファイルやエディターのスワップファイルは無視されます。
• 解析に失敗したファイルの影響は、そのファイル内のプラットフォームのみに限られます。ほかの設定は動作し続けます。
• private_key の相対パスは、どちらの場合も config.json のディレクトリを基準に解決されます。そのため、プラットフォームを config.d/ に移してもパスを変更する必要はありません。
• config.d/ ディレクトリがなければ、動作に変更はありません。

1 つのプラットフォームの不正なブロックによって、ほかのプラットフォームの読み込みが停止してはなりません。 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

1 つの操作と、そこから参照されるすべての components.schemas エントリーを返します。 これにより、完全な仕様書がなくてもリクエストボディを作成できます。サーバー側で管理される認証ヘッダーと QoS ヘッダーは省略されます。

call_endpoint

設定済みの任意のプラットフォームに対して、認証付きリクエストを実行します。署名、認証情報ごとのキャッシュと同時実行の単一化を伴うトークン取得、および 401 の後の 1 回の再試行は、すべてサーバー側で行われます。

応答が truncate_threshold より大きい場合、インラインにはプレビューが表示され、完全なボディは wmt://responses/{request_id}、再現可能な cURL は wmt://curl/{request_id} で取得できます。 ベアラートークン、アクセストークン、署名はプレースホルダーに置き換えられます。

download_file

認証付きエンドポイントからレポート、ラベル、またはスナップショットをダウンロードします。完全な url（たとえば、表示スナップショットのポーリングで得られる details URL）、operation_id、または method と path を指定した api を渡します。platform が必須なのは、修飾なしの url を指定する場合のみです。

dest_path を指定すると、バイト列はそのパスに書き込まれます。指定しない場合、gzip 圧縮されていれば解凍されてキャッシュされ、結果には cached_at が含まれます。dest_path を指定せずにバイナリペイロードを要求すると、保存先パスの指定が求められます。リダイレクトは追従され、相対 URL または同一ホストの Location では認証ヘッダーが維持され、別ホストへのリダイレクトでは認証情報が破棄されます。結果にはリダイレクト経路を示す urls が含まれます。

仕様書

33 個の OpenAPI ドキュメントが wheel に同梱されています。更新すると、更新版が ~/.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

どちらの形式でも、間隔に関係なくすべての仕様を確認し、同じユーザーキャッシュに書き込みます。各ドキュメントにつき 1 行ずつ、written、unchanged、error のいずれかが表示されます。

意図的に、このためのツールはありません。セッション内では、古い仕様も最新の仕様も見分けがつきません。単にエンドポイントが含まれていないだけです。そのため、判断を求められたエージェントは更新を一度も行わないか、無関係な失敗の後にむやみに更新することになります。更新のきっかけはセッションの外に置く必要があります。

インストール前に、ドキュメントから少なくとも 1 つのオペレーションを取得できなければなりません。これにより、エラー本文を含む 200 の応答によってキャッシュが汚染されることを防ぎ、バイト単位で同一のドキュメントはそのまま保持されます。キャッシュ済みのファイルを読み込めない場合は破棄され、読み込みはバンドルにフォールバックします。サーバーはキャッシュのルートにある spec-state.json を通じて連携します。このファイルには各仕様を最後に試行した日時が記録され、同時に 1 つのプロセスだけが一括確認を行うためのリースも保持されます。各クライアントセッションはそれぞれ独自のサーバープロセスを実行するため、これがなければ各プロセスが 33 個すべてを再ダウンロードしてしまいます。

バンドルの再構築

これはメンテナー向けの手順で、--refresh とは異なります。--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

コントリビューション

Issue とプルリクエストを歓迎します。変更の範囲は絞り、ruff check、ruff format --check、pyright、pytest のすべてに必ず合格してください。

ライセンス

LICENSE。