This MCP server provides an integration layer for “Sam's Club Sponsored Ads” APIs. Its purpose is to expose those Sponsored Ads API capabilities through an MCP server interface, enabling developer access and tooling compatibility around the Sam's Club Sponsored Ads API domain.

🛠️ Key Features

MCP server focused on Sam's Club Sponsored Ads APIs

🚀 Use Cases

Accessing Sam's Club Sponsored Ads APIs via MCP

⚡ Developer Benefits

Provides an MCP server entry point for developers working with Sam's Club Sponsored Ads APIs

⚠️ Limitations

Source data does not specify available tools, configuration options, authentication details, or supported operations beyond the Sponsored Ads API scope

Sam's Club Sponsored Ads APIs

MCP server for Sam's Club Sponsored Ads APIs.

Exposes spec-driven discovery (list_endpoints, describe_endpoint), a generic API proxy (call_endpoint), and a runtime spec refresher (refresh_specs). The AI agent discovers endpoints from a bundled OpenAPI spec then calls them; the server handles RSA-SHA256 signing and auth headers automatically.

Forked from mcp-walmart-ads: Sam's Club runs on the same Walmart api-proxy backend and uses the same WM_* signing headers, so the auth, HTTP client, discovery, caching, and tool surface carry over. The differences are a single sponsored ad family (vs Walmart's search/display), the Sam's Club base URLs, and a hand-authored OpenAPI spec.

Features

Spec-driven discovery — list/describe endpoints from a bundled OpenAPI spec, refreshable at runtime
Any endpoint — call by operation id or raw method+path (raw path reaches endpoints not yet in the spec); no code changes when APIs evolve
Multi-region, multi-environment (production + sandbox) via config file
Per-request RSA-SHA256 signing with automatic header construction
Large responses truncated with full data available via MCP resource URI

Requirements

Python 3.13+
Sam's Club Partner credentials (consumer ID, RSA key pair, bearer token) — see Status & blocker

Quick start

Set up your config (see Configuration), then run the server:

bash

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

bash

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

The server speaks MCP over stdio.

Configuration

The config file lives under your home directory at ~/.config/mcp-samsclub-ads/config.json.

Windows note: ~ maps to %USERPROFILE% (typically C:\Users\<you>), so the full path is %USERPROFILE%\.config\mcp-samsclub-ads\config.json.

1. Create the config directory and copy the example

bash

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

powershell

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

2. Edit ~/.config/mcp-samsclub-ads/config.json

json

{
  "response_cache_ttl": 3600,
  "truncate_threshold": 51200,
  "regions": {
    "US": {
      "production": {
        "consumer_id": "your-consumer-id",
        "private_key": "./keys/us/prod.pem",
        "private_key_version": "1",
        "bearer_token": "your-bearer-token",
        "base_urls": {
          "sponsored": "https://developer.api.us.walmart.com/api-proxy/service/sp/api-sams/v1"
        }
      },
      "sandbox": {
        "consumer_id": "your-sandbox-consumer-id",
        "private_key": "./keys/us/sandbox.pem",
        "private_key_version": "1",
        "bearer_token": "your-sandbox-bearer-token",
        "base_urls": {
          "sponsored": "https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1"
        }
      }
    }
  }
}

3. Place your RSA private key PEM files in ~/.config/mcp-samsclub-ads/keys/

Key paths in the config are resolved relative to the config directory, so ./keys/us/prod.pem resolves to ~/.config/mcp-samsclub-ads/keys/us/prod.pem.

Config field	Description
`response_cache_ttl`	Seconds to keep truncated responses in memory (default `3600`)
`truncate_threshold`	Response byte limit before truncation (default `51200`)
`regions.<R>.<E>.consumer_id`	Your Sam's Club consumer ID
`regions.<R>.<E>.private_key`	Path to RSA private key PEM (relative to config dir or absolute)
`regions.<R>.<E>.private_key_version`	Key version string (default `"1"`)
`regions.<R>.<E>.bearer_token`	OAuth bearer token
`regions.<R>.<E>.base_urls.sponsored`	Sponsored Ads API base URL

Each request is signed with WM_CONSUMER.ID, WM_SEC.AUTH_SIGNATURE (Base64 RSA-SHA256), WM_SEC.KEY_VERSION, and WM_CONSUMER.INTIMESTAMP (Unix epoch ms), plus Authorization: Bearer <token> — all injected automatically by the client.

Base URLs

Production: https://developer.api.us.walmart.com/api-proxy/service/sp/api-sams/v1
Sandbox: https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1

Paths in the spec begin /api/v1/... (or /api/v2/...), so the effective URL is <base_url>/api/v1/<resource>.

Tools

`list_endpoints`

List operations from the bundled OpenAPI spec for an ad_type, with optional filters.

Parameter	Required	Description
`ad_type`	yes	`sponsored`
`query`	no	Case-insensitive substring match on operationId, path, or summary
`tag`	no	Filter to operations whose OpenAPI tags include this value
`method`	no	Filter by HTTP verb

`describe_endpoint`

Return one operation plus the components.schemas reachable from it (its $ref closure), so request bodies and responses can be built without the full spec.

Parameter	Required	Description
`ad_type`	yes	`sponsored`
`operation_id`	yes	Spec operation id (from `list_endpoints`)

`call_endpoint`

Execute any Sam's Club Sponsored Ads API endpoint. Identify it by operation_id, or by raw method + path. Raw method+path also reaches endpoints not yet in the bundled spec. The server handles RSA-SHA256 signing.

Parameter	Required	Description
`region`	yes	e.g. `US`
`env`	yes	`production` or `sandbox`
`ad_type`	yes	`sponsored`
`operation_id`	no*	Spec operation id; resolves `method`+`path`
`method`	no*	`GET`, `POST`, `PUT`, `PATCH`, or `DELETE`
`path`	no*	e.g. `/api/v1/campaigns`
`params`	no	Query string parameters (JSON object)
`body`	no	JSON request body for POST/PUT (object or array)

* Provide either operation_id, or both method and path.

`refresh_specs`

Re-fetch the bundled OpenAPI spec from its committed source_url into a user cache (~/.cache/mcp-samsclub-ads/specs/) that takes precedence over the bundled copy — ship fixes without a release.

Parameter	Required	Description
`spec_id`	no	One spec to refresh (e.g. `sponsored/sponsored-ads`); omit to refresh all

MCP resources

Endpoint schemas come from the bundled OpenAPI spec via list_endpoints / describe_endpoint (see Tools), not from static resources.

Dynamic resources

Resource URI	Description
`sca://config`	Available regions, environments, and ad types from your config
`sca://responses/{request_id}`	Full body of a truncated API response (cached in memory, TTL from config)
`sca://curl/{request_id}`	Reproducible cURL command for a previous API request

Spec coverage

The bundled OpenAPI spec is hand-authored from the developer.samsclub.com docs and is partial by design. It covers the core ads surface: Campaigns, Statistics, Ad Groups, Ad Items, Catalog Item Search, Keywords (+ suggestions/analytics), Negative Keywords, Placements, Bid Multipliers, and Snapshot Reports v1/v2 + Latest Report Date. Endpoints not yet modeled (SBA profiles, media, reviews, api-usage, entity/audit snapshots, alerts & recommendations) are still reachable via call_endpoint with a raw method+path.

Status & blocker

Partner credentials are the long pole. Access requires emailing an RSA public key to partner-support@samsclub.com and receiving a consumer id + auth token + key version. Without sandbox credentials the server runs and its discovery/signing are verified offline, but calls cannot be exercised end-to-end.

Spec drift detection

scripts/build_spec.py scrapes the docs into a candidate spec at spec-candidate/ — offline, never at runtime. The Spec drift workflow runs it on a schedule and opens a PR when the docs change; a reviewer then ports real changes into the hand-authored canonical spec. The candidate is intentionally flat and is never shipped or loaded.

bash

uv run --group spec-build python scripts/build_spec.py          # write candidate
uv run --group spec-build python scripts/build_spec.py --check  # exit 1 on drift

Still deferred: flipping a spec's auth flag to fetch the authenticated live Swagger backend once partner credentials exist.

MCP host examples

Cursor

Add to .cursor/mcp.json:

json

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

Claude Code

Add to your Claude Code MCP config:

json

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

Codex

toml

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

OpenCode

json

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

GitHub Copilot

json

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

Development

bash

uv sync --group dev    # install deps
uv run pytest          # run tests
uv run ruff check .    # lint
uv run ruff format .   # format
uv run pyright         # type check

Reference

API docs: https://developer.samsclub.com/API/overview/
Authentication: https://developer.samsclub.com/API/authentication/
Base project: mcp-walmart-ads

Contributing

Open issues or PRs. Follow existing style and add tests where appropriate.

License

MIT. See LICENSE.

Sam's Club Sponsored Ads APIs

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

Sam's Club Sponsored Ads APIs

Features

Requirements

Quick start

Configuration

Base URLs

Tools

`list_endpoints`

`describe_endpoint`

`call_endpoint`

`refresh_specs`

MCP resources

Dynamic resources

Spec coverage

Status & blocker

Spec drift detection

MCP host examples

Cursor

Claude Code

Codex

OpenCode

GitHub Copilot

Development

Reference

Contributing

License

Install