shoplazza-mcp

Shoplazza OpenAPI（REST）를 MCP (Model Context Protocol) 서비스로 감싼 Python 구현체로, Claude, Cursor, DSH 등 MCP를 지원하는 클라이언트가 Shoplazza 스토어 데이터를 (상품, 주문, 고객, 재고, 할인, 웹훅 구독 등) 직접 읽고 쓸 수 있습니다.

엔드포인트 카탈로그(data/endpoints.json)는 tools/scrape_endpoints.py가 공식 문서에서 자동으로 수집하며, 2026-01 버전 기준 총 311개의 실제 엔드포인트, 46개 리소스 그룹을 포함합니다.

기능 특성

설치

요구 사항: Python ≥ 3.10, uv(권장) 또는 pip.

cd shoplazza-mcp
uv sync          # 创建 .venv 并安装依赖（mcp、httpx）

uv를 사용하지 않을 때:

python -m venv .venv
.venv\Scripts\activate   # Windows
pip install -e .

설정

자격 증명은 환경 변수로 제공합니다(비밀 키를 코드에 작성하거나 저장소에 커밋하지 마세요):

# PowerShell / cmd
set SHOPLAZZA_SHOP_DOMAIN=your-store.myshoplazza.com
set SHOPLAZZA_ACCESS_TOKEN=your-access-token

* 단일 스토어 구성 SHOPLAZZA_SHOP_DOMAIN + SHOPLAZZA_ACCESS_TOKEN와 멀티 스토어 구성 SHOPLAZZA_STORES 중 하나만 선택하면 됩니다. 둘 다 설정하면 SHOPLAZZA_SHOP_DOMAIN이 기본 스토어가 됩니다.

전체 예시는 .env.example을 참고하세요.

다중 스토어 사용법

여러 스토어를 구성하면 서비스의 모든 API 도구에 선택적 shop_domain 파라미터가 추가됩니다:

export SHOPLAZZA_STORES='{"us.myshoplazza.com":"token-us","de.myshoplazza.com":"token-de"}'

• shop_domain 없음 → 기본 스토어 사용(SHOPLAZZA_SHOP_DOMAIN 또는 STORES의 첫 번째 항목)

• shop_domain 지정 → 지정된 스토어 사용(알 수 없는 스토어는 오류를 반환하고 구성된 스토어 목록을 표시)

• shoplazza_list_shops → 서비스에 구성된 모든 스토어와 기본 스토어 확인

• 각 스토어는 독립적인 Access-Token과 독립 속도 제한 버킷을 가집니다(공식 스토어별 제한 규칙 준수), 멀티 스토어 간 서로 블로킹되지 않습니다.

대화 예시:

“US 스토어의 오늘 주문량을 확인하고, DE 스토어에서 판매량 상위 5개 상품도 확인해줘” → 모델은 각각 shop_domain=us.myshoplazza.com 및 shop_domain=de.myshoplazza.com으로 shoplazza_orders / shoplazza_products를 호출합니다.

Claude Desktop 구성 예시(다중 스토어):

{
  "mcpServers": {
    "shoplazza": {
      "command": "uv",
      "args": ["run", "--directory", "D:/projects/DSH-projects/shoplazza-mcp", "shoplazza-mcp"],
      "env": {
        "SHOPLAZZA_STORES": "{\"us.myshoplazza.com\":\"token-us\",\"de.myshoplazza.com\":\"token-de\"}"
      }
    }
  }
}

필요한 API 권한(scope)

파트너 센터에서 앱을 생성/설치하거나 스토어에 권한을 부여할 때, “최소 권한 원칙”에 따라 필요한 scope만 요청하세요. 데이터 조회에는 read_*, 수정이 필요할 때만 동일한 이름의 write_*를 추가하세요:

읽기 전용 운영 시나리오 권장 조합: read_shop, read_product, read_order, read_customer, read_price_rules, read_gift_cards, read_shop_navigation, read_data. 권한 부여 후 shoplazza_oauth_access_scopes 도구를 호출해 이번 설치에서 실제로 부여된 scope를 확인할 수 있습니다. 공식 전체 매핑은 접근 권한 범위를 참고하세요.

Access Token 가져오는 방법

• 공개 앱: OAuth 2.0 Authorization Code 흐름에 따라 code로 access_token을 교환합니다(유효 기간 1년, refresh_token으로 갱신 가능).

• 비공개 / 내부 통합: Shoplazza 관리자에서 앱과 스토어에 해당하는 액세스 토큰을 생성합니다.

실행

stdio(로컬 MCP 클라이언트, 기본)

uv run shoplazza-mcp

HTTP(원격 서비스)

uv run shoplazza-mcp --transport http --host 0.0.0.0 --port 8765

엔드포인트 경로는 기본적으로 /mcp이며 --http-path로 변경할 수 있습니다.

MCP 클라이언트 연결

Claude Desktop(claude_desktop_config.json):

{
  "mcpServers": {
    "shoplazza": {
      "command": "uv",
      "args": ["run", "--directory", "D:/projects/DSH-projects/shoplazza-mcp", "shoplazza-mcp"],
      "env": {
        "SHOPLAZZA_SHOP_DOMAIN": "your-store.myshoplazza.com",
        "SHOPLAZZA_ACCESS_TOKEN": "your-access-token"
      }
    }
  }
}

Cursor: 설정 → MCP에서 서버를 추가하세요. 구성은 examples/mcp-cursor.json을 참고하세요.

원격 HTTP(모든 클라이언트): url을 http://host:8765/mcp로 지정하세요.

직접 실행할 수도 있습니다(debug로 도구 목록 및 JSON-RPC 상호 작용 확인):

uv run mcp dev shoplazza-mcp

사용 예시(Claude / Cursor 등 대화)

• 스토어의 최신 주문 10개를 나열해줘

• 상품 abcd-1234의 재고를 확인해줘

• 주문 order-xxx을 취소하고 사유는 customer requested로 작성해줘

• 100 이상 구매 시 20 할인되는 할인을 새로 만들어줘

• “환불에 사용할 수 있는 API가 뭐야? 엔드포인트를 검색해봐” → 모델이 shoplazza_search_endpoints("refund")를 호출한 후 해당 엔드포인트를 자동으로 호출합니다.

모든 응답은 API 원본 패킷인 {code, message, data, api_call_limit}을 반환합니다. 목록 유형 응답은 data에 cursor / pre_cursor를 포함하며, page_size / per_page 파라미터와 함께 페이지네이션합니다.

개발 및 유지보수

• tools/scrape_endpoints.py: 공식 엔드포인트 문서 페이지에서 수집해 data/endpoints.json을 생성합니다(각 엔드포인트의 method / path / 파라미터 / 요청 본문 필드 / 응답 구조 포함).

• 간편 유지보수: '일반 도구'를 추가하거나 제거할 때는 shoplazza_mcp/tools.py의 CURATED_SLUGS 목록만 수정하면 됩니다.

• scripts/smoke_test.py: 오프라인 스모크 테스트(stdio); scripts/http_smoke_test.py: HTTP 스모크 테스트.

보안 안내

• Access Token은 환경 변수 / 클라이언트 구성으로만 주입하고 코드 저장소에 작성하지 마세요.

• 서비스는 HTTPS만 사용합니다(공식적으로 모든 엔드포인트는 HTTPS 전용).

• HTTP 서비스를 외부 네트워크에 노출할 때는 신뢰할 수 있는 내부 네트워크에 두거나 게이트웨이, 방화벽 등 자체 인증을 추가하세요.

License

MIT