Walmart Marketplace APIs

Walmart Marketplace APIs용 MCP 서버 — 아이템, 주문, 재고, 가격, 프로모션, 피드, 보고서, 반품, 풀필먼트 등.

스펙 기반 탐색(list_endpoints, describe_endpoint), 범용 API 프록시(call_endpoint), 피드 업로드 및 파일 다운로드 헬퍼, 런타임 스펙 새로고침(refresh_specs)을 제공합니다. AI 에이전트는 번들된 OpenAPI 스펙에서 엔드포인트를 탐색한 후 호출하며, 서버가 OAuth2 토큰 획득, 갱신, Walmart 필수 헤더를 자동으로 처리합니다. 기본 주소는 환경별로 하드코딩되어 있으므로, 설정 파일에는 자격 증명만 담깁니다.

기능

• 스펙 기반 탐색 — 234개 작업을 포함하는 28개의 번들 OpenAPI 스펙, 런타임에 새로고침 가능

• 모든 엔드포인트 — 작업 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

요구 사항

• 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\GXP3입니다.

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_SSON 헤더 값.

지역

지역은 경로가 아닌 네임스페이스입니다. 기본 주소는 환경별로 서버에 의해 고정되므로 모든 지역이 동일한 Walmart 호스트에 도달합니다. 어드바이저 ID가 한 지역 내에서만 고유하면 되도록 수준이 존재합니다 — 두 지역에서 동일한 ID는 서로 다른 자격 증명을 가진 다른 판매자를 의미할 수 있습니다.

파트너 ID

Walmart 파트너 ID가 있는 판매자에 partner_id를 추가합니다:

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

두 payments 작업 — payments:getTaxForms 및 payments:파트너 ID — WM_PARTNER_ID 헤더로 필요합니다. 파트너 ID가 없는 판매자에 대해 호출하면 Walmart 400 대신 추가하라는 메시지와 함께 실패합니다. 다른 모든 작업은 이를 무시하므로 대부분의 항목은 {"id": …}입니다.

어드바이저

advertiser_네트워크 필수 모든 네트워크에 도달하는 모든 도구에 대한 기본값은 없습니다. 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/스펙/)에서 로드하고, 휠에 포함된 사본으로 대체되므로 refresh_specs는 재설치 없이 즉시 적용됩니다.

디스크의 파일은 레지스트리가 제공한 그대로 그대로 저장되므로 번들이 진실의 원천이며, 새로고침 차이는 Walmart가 변경한 내용을 정확히 보여줍니다. 로드 시 축소가 발생하므로 런타임 정책으로 유지됩니다:

• 과도하게 큰 예제는 삭제됩니다. 3,514개의 인라인 example 페이로드가 총 4.13 MB이지만 중앙값은 16바이트이고 두 개의 /v3/날짜 페이로드가 3.25 MB를 차지합니다. MAX_EXAMPLE_BYTES(1 KB) 이하의 모든 항목은 97%가 살아남아 ~133 KB로 날짜, SKU, 식별자에 대한 형식 힌트가 에이전트에 도달하지 못하는 괴물이 없도록 합니다.

• x-readme는 제거됩니다 — 문서 플랫폼 렌더링 메타데이터, API 세부 정보가 아닙니다.

모든 28개 스펙 로드 비용은 프로세스당 ~80 ms이며, 스펙별로 결과가 캐시되고 파일 mtime으로 무효화되므로 refresh_s기존이 즉시 적용됩니다. 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

주의 사항

스펙과 API는 인증에 대해 의견이 다릅니다. 76개 작업이 클라이언트 ID와 시크릿으로 구성된 Basic Authorization 헤더를 선언하고, fulfillment-management 및 Basic이 액세스 토큰 대신 요구하는 것으로 보입니다. 프로덕션에서 조사한 결과, 이는 잘못된 것입니다: Basic만으로는 401을 반환하고, 액세스 토큰만으로는 모든 테스트 서비스에서 200을 반환합니다. 따라서 이 서버는 모든 요청에 WM_SEC.참조를 보내고 /v3/token 외에는 클라이언트 시크릿을 보내지 않습니다. 참조 문서와 동작을 비교하면 그 차이는 의도적입니다.

WM_SVC.NAME은 스펙에서 읽을 수 없습니다. 103개 작업이 리터럴 자리 표시자 문자열 "Walmart Service Name"을 선언하고 100개만 실제 값을 선언하므로 Walmart Marketplace로 고정되어 라이브 호출로 확인됩니다.

모든 문서화된 엔드포인트가 판매자 자격 증명으로 도달할 수 있는 것은 아닙니다. GET /v3/utilities/apiStatus는 wm_svc.name: PARTNERMANAGEMENTSERVICES 및 wm_svc.env: prod를 예상 헤더로 명명하며 HTTP 520 Unable to route request를 반환하지만, 정확히 그 헤더를 보내도 여전히 520을 반환합니다. 3P 자격 증명이 도달할 수 없는 서비스에 속하는 것으로 보이며 오류 메시지는 오해의 소지가 있습니다. 234개 작업 중 소수의 유사한 사례가 있을 것으로 예상됩니다.

보고서 엔드포인트는 콘텐츠 협상을 엄격하게 처리합니다. Accept: */*를 406으로 거부하고 생성할 수 있는 항목을 나열하므로 Accept는 작업이 성공 응답에 대해 선언한 미디어 유형에서 파생됩니다(제공될 때 application/json 선호). 응답 콘텐츠를 선언하지 않는 엔드포인트를 추가하면 */*로 대체되어 406이 발생할 수 있습니다.

라이브 커버리지는 얇습니다. 5개 도메인의 7개 작업이 프로덕션에서 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은 프로덕션에서 검증되었습니다.

크로스 호스트 리디렉션 경로는 실행되지 않았습니다. download_file은 리디렉션이 Walmart 호스트를 벗어날 때 자격 증명을 제거하며, 보고서가 서명된 스토리지에서 제공되는 경우 중요합니다. 지금까지 관찰된 모든 다운로드는 한 홉으로 직접 바이트를 반환했으므로 해당 분기는 단위 테스트 커버리지만 있습니다.

라이선스

MIT