mcp-walmart-marketplace

MCP server forWalmart Marketplace APIs— items, orders, inventory, prices, promotions, feeds, reports, returns, fulfillment, and more.

- Python 3.13+
- Walmart Marketplace client ID and client secret per seller (Developer Portal)

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

# 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

mkdir -p ~/.config/mcp-walmart-marketplace cp config.example.json ~/.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 }] } ] } } } }

Keep the config file readable only by you — it holds client secrets in plain text.

Everything else is fixed by the server: base URLs (marketplace.walmartapis.comfor production,sandbox.walmartapis.comfor sandbox),WM_SVC.NAME, theclient_credentialsgrant, and the per-operationWM_MARKET/WM_SANDBOXheader values.

A region is a namespace, not a route. Base addresses are fixed by the server per environment, so every region reaches the same Walmart hosts. The level exists so advertiser ids only have to be unique within one region — the same id under two regions can mean different sellers with different credentials.

Addpartner_idto a seller that has a Walmart Partner ID:

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

Twopaymentsoperations —payments:getTaxFormsandpayments:downloadTaxForm— require it as theWM_PARTNER_IDheader. Calling one for a seller configured without a partner id fails with a message telling you to add it, rather than a Walmart 400. Every other operation ignores it, so most entries are just{"id": …}.

advertiser_idisrequiredon every tool that reaches the network; there is no default. Read thewmm://configresource to discover which advertiser ids are configured. It reports region, environment, and advertiser ids only — never client ids or secrets.

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

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

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

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

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

The 28 bundled specs come from the ReadMe api-registry that backsdeveloper.walmart.com. They load from the user cache dir first (~/.cache/mcp-walmart-marketplace/specs/) and fall back to the copy shipped in the wheel, sorefresh_specstakes effect immediately without a reinstall.

The files on disk are storedverbatimas the registry served them, so the bundle is the source of truth and a refresh diff shows exactly what Walmart changed. Reduction happens on load, which keeps it a runtime policy rather than something baked into the files:

- Oversized examples are dropped.There are 3,514 inlineexamplepayloads totalling 4.13 MB, but the median is 16 bytes and two/v3/items/taxonomypayloads account for 3.25 MB. Everything at or underMAX_EXAMPLE_BYTES(1 KB) survives — 97% of them, for ~133 KB — so format hints for dates, skus, and identifiers stay available while the monsters never reach an agent.
- x-readmeis removed— docs-platform rendering metadata, not API detail.

Cost of loading all 28 specs is ~80 ms once per process; results are cached per spec and invalidated by file mtime, so arefresh_specstakes effect immediately.describe_endpointoutput is 5.1 KB at the median and 88 KB at the worst (sixorder-managementoperations inline very large response schemas).

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

The specs and the API disagree about authentication.76 operations declare a BasicAuthorizationheader built from the client id and secret, andfulfillment-managementandinsights-managementappear to require itinstead ofan access token. Probed against production, that is wrong: Basic alone returns 401, the access token alone returns 200, on every service tested. This server therefore sendsWM_SEC.ACCESS_TOKENon every request and never sends the client secret anywhere except/v3/token. If you diff its behavior against the reference docs, that gap is deliberate.

WM_SVC.NAMEcannot be read from the specs.103 operations declare the literal placeholder string"Walmart Service Name"and only 100 the real value, so it is fixed atWalmart Marketplace, which live calls confirm.

Not every documented endpoint is reachable with seller credentials.GET /v3/utilities/apiStatusreturns HTTP 520Unable to route request, namingwm_svc.name: PARTNERMANAGEMENTSERVICESandwm_svc.env: prodas the expected headers — but sending exactly those still returns 520. It appears to belong to a service that 3P credentials cannot reach, and the error message is a red herring. Expect a handful of similar cases across 234 operations.

Report endpoints negotiate content strictly.They rejectAccept: /with a 406 listing what they can produce, soAcceptis derived from the media types the operation declares for its success responses (preferringapplication/jsonwhen offered). If you add an endpoint whose spec declares no response content, it falls back to/and may 406.

Live coverage is thin.Seven operations across five domains have returned 200 against production —feed-management,advertising,fulfillment-management,insights-management,settings-management— including two report downloads that arrive as real Excel workbooks. The other ~227 are wired from the specs and have never been called. Discovery and request construction are covered by tests; upstream behavior is not.

Two known upstream failures, neither a client bug:fulfillment-management:getInventoryHealthReportanswers 520WFS_INTERNAL_SERVER_ERROR, andfeed-management:getFeedErrorReportanswers 404 for a feed that processed cleanly.

Sandbox is unverified.Walmart issues sandbox credentials separately from production, and nothing here has run againstsandbox.walmartapis.com. TheWM_SANDBOX: v2handling — which opts into thedynamicsandbox and changes response semantics rather than just routing — is implemented from the specs, not observed.

upload_feedis untested end to end.It is exercised by unit tests against a scripted transport only — the sole way to verify it live is to submit a real feed, which mutates a live catalog.download_filehasbeen verified against production.

The cross-host redirect path is unexercised.download_filesheds credentials when a redirect leaves Walmart's host, which matters if a report is ever served from signed storage. Every download observed so far returned its bytes directly, in one hop, so that branch has only unit-test coverage.

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

Hosted Amazon Seller Central and Amazon Ads MCP server for Claude, ChatGPT, Cursor, Claude Code, OpenClaw, and HTTP-capable MCP clients.

A read-only MCP server for querying live eBay data. Requires a separately licensed CData JDBC Driver for eBay.

A TypeScript-based MCP server for interacting with the Etsy API, featuring a simple notes system.

Real-time Amazon data API built for AI agents. 200M+ products, 1B+ reviews, live BSR, pricing, and competitor data as clean JSON. 10 agent skills for market research, competitor monitoring, pricing, listing audits, and more. 1,000 free credits.

A command-line tool for interacting with Shopify's Admin GraphQL API, Functions, and Polaris Web Components.

A Model Context Protocol (MCP) server for square

Installable MCP server for AgentLux marketplace, identity, creator, services, social, and Base/x402 commerce flows.

Integrate AI tools and agents with Cashfree's Payment Gateway, Payouts, and SecureID APIs.

Read-only MCP server for GST Cranes public developer docs, OpenAPI, marketplace listings, wanted ads, and Crane Wiki resources.