sellercloud-mcp

SellerCloud을 위한 최초의 Model Context Protocol 서버입니다. 5분 안에 Claude를 카탈로그, 재고, 주문 및 채널 목록에 읽기 전용으로 연결하세요.

존재 이유

SellerCloud은 공개 SDK가 없습니다. REST API는 잘 문서화되어 있지만 브랜드화되어 있지 않아, 이를 자동화하는 모든 팀은 매번 동일한 인증 및 페이지네이션 코드를 처음부터 작성해야 합니다.

일상적인 전자상거래 운영을 위해 Claude(또는 MCP를 지원하는 AI 어시스턴트)를 사용하는 경우, 이러한 격차는 "오늘의 주문 요약해 줘"가 즉시 작동하는 것과 사용자 지정 통합이 필요한 것의 차이를 만듭니다.

sellercloud-mcp는 그 격차를 해소합니다. 이 서버는 7개의 읽기 전용 SellerCloud 엔드포인트를 모든 MCP 클라이언트에 노출하는 작고 잘 테스트된 MIT 라이선스 MCP 서버입니다. 대규모 전자상거래 자동화를 운영해 온 수년간의 경험을 바탕으로 구축되었습니다.

Related MCP server: Amazon Marketplace MCP Server by CData

활용 방법

이 서버를 Claude Code, Claude Desktop 또는 모든 MCP 호스트에 연결한 후 다음과 같이 질문해 보세요:

• "WIDGET이 포함된 SKU를 검색하고 재고 수준을 보여줘."

• "어제 모든 마켓플레이스에서 배송된 주문은 총 몇 건인가요? 채널별로 그룹화해 줘."

• "주문 100001을 가져와서 어떤 품목이 배송되었는지 알려줘."

• "회사 9001에 구성된 채널을 나열하고 활성화된 채널을 보여줘."

• "SKU ACME-001에 대해 모든 채널 목록의 가격을 비교해 줘."

Claude가 카탈로그를 직접 읽습니다. 복사-붙여넣기, 스프레드시트, 사용자 지정 파이프라인이 필요 없습니다.

도구 (v0.1, 모두 읽기 전용)

쓰기 엔드포인트(주문 생성, 재고 업데이트, 채널 변경 푸시)는 의도적으로 v0.1에 포함되지 않았습니다. 읽기 전용 기능이 안정화된 후 v0.2에서 계획될 예정입니다.

설치

pip install sellercloud-mcp

v0.1은 이 저장소에서 제공됩니다. PyPI 배포는 대기 중입니다. 현재는 pip install git+https://github.com/alveyautomation/sellercloud-mcp를 사용하거나 로컬에서 복제 후 pip install -e .를 실행하여 설치하세요.

자격 증명 구성

서버는 모든 정보를 환경 변수에서 읽습니다. .env.example을 .env로 복사하고 테넌트 정보를 입력하세요:

SELLERCLOUD_API_URL=https://your-team.api.sellercloud.com/rest/
SELLERCLOUD_USERNAME=your-username
SELLERCLOUD_PASSWORD=your-password
SELLERCLOUD_DEFAULT_COMPANY_ID=        # optional fallback
SELLERCLOUD_HTTP_TIMEOUT=60            # optional, seconds
SELLERCLOUD_MAX_RETRIES=3              # optional

읽기 전용 SellerCloud 계정을 사용하세요. v0.1은 GET 엔드포인트만 호출하지만, 심층 방어 차원에서 아무것도 수정할 수 없는 전용 사용자를 서버에 제공해야 합니다. v0.2에서 쓰기 도구가 추가되면 자격 증명을 업그레이드하여 선택적으로 사용하세요. 반대로 해서는 안 됩니다.

Claude Code에 연결

~/.claude/claude_code_config.json(또는 프로젝트의 MCP 구성)에 추가하세요:

{
  "mcpServers": {
    "sellercloud": {
      "command": "sellercloud-mcp",
      "env": {
        "SELLERCLOUD_API_URL": "https://your-team.api.sellercloud.com/rest/",
        "SELLERCLOUD_USERNAME": "your-username",
        "SELLERCLOUD_PASSWORD": "your-password",
        "SELLERCLOUD_DEFAULT_COMPANY_ID": "9001"
      }
    }
  }
}

Claude Code를 재시작하세요. 새로운 세션에서 7개의 sellercloud_* 도구가 나타납니다.

Claude Desktop에 연결

~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json(Windows)을 편집하고 위와 동일한 mcpServers 블록을 추가하세요. 데스크톱 앱을 재시작하세요.

도구 참조

모든 도구는 JSON 봉투를 반환합니다:

{ "ok": true,  "data": { ... } }
{ "ok": false, "error": "human-readable message" }

sellercloud_search_products

sellercloud_search_products(
    query: str,                          # required
    company_id: int | None = None,       # falls back to default if unset
    page: int = 1,
    page_size: int = 50,                 # capped at 50 by SellerCloud
)

응답 예시:

{
  "ok": true,
  "data": {
    "items": [
      { "ID": "ACME-WIDGET-001", "ProductName": "Acme Widget, Standard", "Price": 29.99 }
    ],
    "total": 1,
    "page": 1,
    "page_size": 50
  }
}

sellercloud_get_product

sellercloud_get_product(sku: str, company_id: int | None = None)

카탈로그 레코드를 반환하거나, SKU가 회사 카탈로그에 없으면 data: null을 반환합니다.

sellercloud_search_orders

sellercloud_search_orders(
    date_from: str,                      # ISO date "YYYY-MM-DD"
    date_to: str,                        # ISO date "YYYY-MM-DD"
    company_id: int | None = None,
    query: str | None = None,
    limit: int = 200,                    # max 1000
)

페이지네이션은 투명하게 처리됩니다. SellerCloud는 페이지 크기를 50으로 제한하지만, 도구는 limit까지 페이지를 수집합니다. limit보다 많은 주문이 있는 경우 응답에 limit_reached: true가 포함됩니다.

sellercloud_get_order

sellercloud_get_order(order_id: int)

전체 주문 레코드(Items[] 포함)를 반환하거나, 404인 경우 data: null을 반환합니다.

sellercloud_get_inventory

sellercloud_get_inventory(sku: str, company_id: int | None = None)

반환된 레코드에는 다음이 포함됩니다:

• InventoryAvailableQty — API가 현재 판매 가능하다고 판단하는 수량

• PhysicalQty — 실제 재고

• ReservedQty — 미결 주문을 위해 보류된 수량

• OnOrder — 입고 예정 PO 수량

"판매 가능한 수량"을 나타내는 표준 값으로 InventoryAvailableQty를 사용하세요.

sellercloud_list_channels

sellercloud_list_channels(company_id: int | None = None)

회사에 대해 구성된 채널 피드 목록을 반환합니다. 각 레코드에는 ChannelID, Name, Active가 포함됩니다.

sellercloud_get_channel_listing

sellercloud_get_channel_listing(channel_id: int, sku: str)

채널별 목록 세부 정보입니다. 마켓플레이스 전반의 가격을 현장 점검하는 데 유용합니다.

로컬 개발

git clone https://github.com/alveyautomation/sellercloud-mcp
cd sellercloud-mcp
python -m venv .venv && source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest                                                # 44 tests, ~4s

Pre-commit 훅 (gitleaks, ruff, formatter, tenant-fingerprint scrubber):

pip install pre-commit
pre-commit install

실제 SellerCloud 샌드박스 계정에 대한 통합 테스트는 SELLERCLOUD_INTEGRATION_TESTS=1로 제한되어 있습니다. 일반적인 기여에는 필요하지 않습니다.

문제 해결

Failed to obtain SellerCloud token — 사용자 이름/비밀번호가 거부되었습니다. 가장 흔한 원인: 계정에 2FA가 활성화되어 있거나 잠겨 있습니다. SellerCloud의 POST /api/token 엔드포인트는 2FA가 없는 서비스 계정을 기대합니다.

Missing required environment variables — .env가 로드되기 전에 서버가 시작되었습니다. 부모 셸에서 변수를 내보내거나 MCP 호스트 구성의 env 블록에 포함되어 있는지 확인하세요.

데이터가 있음에도 결과가 비어 있음 — company_id가 올바른지 확인하세요. SellerCloud는 companyID를 명시적으로 전달하지 않으면 인증된 사용자의 기본 회사 정보만 반환합니다.

페이지네이션이 느림 — 페이지 크기는 우리가 아닌 SellerCloud에 의해 50으로 제한됩니다. 큰 날짜 범위의 경우 여러 번의 왕복 통신이 발생할 수 있습니다.

기여

이슈와 풀 리퀘스트를 환영합니다. 다음을 준수해 주세요:

• PR을 열기 전에 pytest를 실행하세요 (pip install -e ".[dev]").

• pre-commit run --all-files를 실행하세요.

• v0.1 범위에 대한 추가 사항은 읽기 전용으로 유지하세요. 쓰기 엔드포인트는 v0.2에 포함됩니다.

• 테스트에는 합성 데이터만 사용하세요. 실제 SKU, 고객 이름, 주문 번호는 사용하지 마세요.

라이선스

MIT — LICENSE를 참조하세요.

면책 조항

sellercloud-mcp는 비공식 타사 통합 도구입니다. SellerCloud, Inc.의 보증, 제휴 또는 지원을 받지 않습니다. "SellerCloud"는 SellerCloud, Inc.의 상표입니다. 사용자의 책임하에 사용하시고, 프로덕션 결정에 의존하기 전에 테넌트에서 동작을 확인하세요.