@marketbasketanalysis/mcp

이 MCP 서버는 전자상거래 판매자의 주문 이력에서 얻은 실제 동반 구매 인텔리전스와 판매자 운영 도구를 모든 AI 에이전트가 사용할 수 있게 해 줍니다. 디스커버리, 번들, 인사이트, 재입고, 판매자 운영, 고급 마이닝에 걸친 19개 도구를 제공합니다. Claude Desktop, Claude Code, Cursor, Windsurf, Cline, OpenAI Agent SDK 및 MCP stdio 프로토콜을 지원하는 다른 모든 호스트에서 작동합니다. Shopify, BigCommerce, WooCommerce, Magento, OroCommerce를 사용하는 판매자에게도 작동합니다. 셀프 호스팅 백엔드에 도달하는 도구는 아래 "플랫폼 적용 범위"를 참조하세요.

하나의 npm 패키지가 모든 마켓플레이스를 지원합니다. 이 서버는 플랫폼에 구애받지 않으며, 공개 REST API를 통해 상점의 MBA 백엔드를 호출하는 HTTP 클라이언트입니다. 단일 스위치(MBA_API_BASE, 아래 참조)로 전체 서버를 어떤 상점으로든 다시 연결할 수 있습니다. 대부분의 도구는 5개 플랫폼 모두에서 작동합니다. 일부 도구는 아직 모든 플랫폼이 제공하지 않는 백엔드 라우트에 의존합니다. 도구별 마켓플레이스 적용 범위는 도구 카탈로그의 "마켓플레이스" 열에 나와 있습니다.

왜 필요한가

고객이 AI 쇼핑 에이전트에게 "짐 백팩에 어울리는 건 뭐예요?"라고 물으면, 에이전트는 판매자의 실제 주문 데이터에 기반한 실제 답변을 해야 하며, 일반적인 "이것도 좋아할 만한" 추측이 아니라 구체적인 답을 내놓아야 합니다. 판매자가 Claude에게 "이번 주에는 무엇에 집중해야 할까요?"라고 물으면, 에이전트는 우선순위가 매겨진 주간 계획에서 답을 끌어와야 하며, 작업을 지어내서는 안 됩니다. 이 서버는 이 두 흐름을 모두 한 줄의 구성으로 모든 MCP 호스트에서 사용할 수 있게 합니다.

5줄 설치 (Claude Desktop)

{
  "mcpServers": {
    "marketbasketanalysis": {
      "command": "npx",
      "args": ["-y", "@marketbasketanalysis/mcp"],
      "env": { "MBA_API_KEY": "mba_live_YOUR_KEY_HERE" }
    }
  }
}

~/Library/Application Support/Claude/claude_desktop_config.json(macOS)에 붙여넣고, Claude Desktop을 다시 시작하면 marketbasketanalysis 서버가 전체 19개 도구와 함께 도구 목록에 나타납니다.

제로 설치: 호스팅 엔드포인트

동일한 서버가 https://mcp.marketbasketanalysis.com/mcp에서 호스팅되어 실행됩니다(MCP streamable HTTP). 설치할 것이 없습니다. 환경 변수 대신 Bearer 헤더로 키를 보내면 됩니다:

claude mcp add --transport http marketbasketanalysis \
  https://mcp.marketbasketanalysis.com/mcp \
  --header "Authorization: Bearer mba_live_YOUR_KEY_HERE"

원격 연결이 가능한 모든 MCP 클라이언트(Claude Code, Cursor, Smithery, 커스텀 에이전트)에서 작동합니다. 선택적 헤더: X-MBA-Base는 다른 MBA 운영 플레인을 가리킵니다(예: https://bigcommerce.marketbasketanalysis.com). X-MBA-Platform은 MBA_PLATFORM 환경 변수를 미러링합니다. 셀프 호스팅 WooCommerce 및 Magento 상점은 설계상 호스팅 엔드포인트에서 도달할 수 없습니다. 위의 npx 설치를 사용하고 MBA_API_BASE를 자신의 사이트로 지정하세요.

서버를 상점으로 연결하기 (MBA_API_BASE)

기본 URL은 상점별 구성입니다. 기본적으로 서버는 공유 호스팅 백엔드 https://app.marketbasketanalysis.com과 통신합니다. 데이터가 다른 곳(BigCommerce 상점, 셀프 호스팅 백엔드, 스테이징 인스턴스 등)에 있다면 MBA_API_BASE를 설정하여 모든 도구가 자체 데이터 플레인에 도달하도록 하세요:

{
  "mcpServers": {
    "marketbasketanalysis": {
      "command": "npx",
      "args": ["-y", "@marketbasketanalysis/mcp"],
      "env": {
        "MBA_API_KEY": "mba_live_YOUR_KEY_HERE",
        "MBA_API_BASE": "https://your-store-backend.example.com"
      }
    }
  }
}

MBA_API_BASE는 전체 서버를 다시 연결하는 단일 스위치이며, 19개 도구 모두 이를 통해 라우팅됩니다. 비로컬 호스트의 경우 값은 https:// URL이어야 합니다(루프백, 사설, 링크-로컬, 메타데이터 서비스 호스트는 거부됨). localhost의 백엔드를 대상으로 하는 로컬 개발에서는 ALLOW_LOCAL_API_BASE=1을 설정하여 http://localhost 기본 URL을 허용할 수 있습니다. 환경 변수 변경은 서버 시작 시 적용되므로, 값을 편집한 후 MCP 호스트를 다시 시작하세요.

플랫폼별 MBA_API_BASE

기본 URL은 상점별 구성입니다. Shopify, BigCommerce, OroCommerce 상점은 공유 호스팅 백엔드가 제공하므로 기본값을 사용합니다. WooCommerce와 Magento는 상점 설치 내부에서 백엔드를 로컬로 실행하므로, 서버를 상점의 자체 도메인으로 연결하세요:

플랫폼 적용 범위

서버는 표준 /api/v1/... 경로를 작성한 다음 플랫폼별로 다시 작성합니다. WooCommerce와 Magento는 상점 내부에서 자체 REST 규칙에 따라 백엔드를 실행하기 때문입니다(각각 marketbasketanalysis/v1 및 V1/marketbasketanalysis).

19개 도구 중 10개가 WooCommerce와 Magento에 도달합니다: /recommendations에서 파생되는 6개(get_recommendations, get_bundle_for_cart, score_cross_sell, analyze_basket, propose_subscription_bundle, score_return_risk)와 find_substitutes, get_rationale, forecast_bundle, predict_reorder입니다.

나머지 9개는 판매자 운영 영역입니다: get_opportunities, triage_opportunity, get_weekly_plan, execute_weekly_plan_action, get_drift_alerts, get_forecast_alerts, explain_opportunity, explain_drift, mine_hui_itemsets. 이러한 엔드포인트는 셀프 호스팅 백엔드에 존재하지 않습니다. 해당 백엔드에서 호출하면 불투명한 404 대신 엔드포인트 이름을 명시한 "이 플랫폼에서는 사용할 수 없음" 오류가 네트워크 왕복 없이 반환됩니다.

단계별 설치 방법(OS별 구성 파일 위치, API 키 발급 위치, 문제 해결):

• Claude Desktop: dist/mcp/claude-desktop-setup.md

• Cursor: dist/mcp/cursor-setup.md

• Windsurf: dist/mcp/windsurf-setup.md

인증

서버는 MCP 호스트가 전달하는 환경에서 MBA_API_KEY를 읽고, 모든 요청에서 이를 Bearer 토큰으로 보냅니다. 키를 얻으려면:

1. MarketBasketAnalysis 관리자(Shopify 앱 서랍 또는 BigCommerce / WooCommerce / Magento / OroCommerce 관리자)를 엽니다.

2. 왼쪽 내비게이션에서 "API 키"를 클릭합니다.

3. "키 생성"을 클릭하고 이름을 지정한 다음 mba_live_ 값을 복사합니다(한 번만 표시됩니다).

키는 상점별로 제공되며, 같은 화면에서 취소하거나 순환할 수 있습니다. SHA-256 해시만 저장되므로, 키가 유출되면 다시 발급하세요.

인증 모델은 마켓플레이스마다 다르며, MCP 서버가 이를 추상화하지만 알아두면 좋습니다:

• Shopify, BigCommerce: Bearer mba_live_...를 그대로 전달합니다. 이것이 일반적인 경로입니다.

• WooCommerce: Bearer는 Woo에서 발급한 키에 대해 사용되며, 해당 키는 predict_reorder를 위해 customer_data 범위를 보유해야 합니다.

• Magento: 도구는 Magento REST 표면(/V1/marketbasketanalysis/* 및 /V1/mba/*)을 통해 상점에 도달합니다. 일부 라우트는 상점 측에서 관리자 토큰 / ACL 범위로 제한됩니다.

• OroCommerce: 상점은 /api/ 라우트에 대해 플랫폼 OAuth2 방화벽 뒤에 있습니다. 얇은 클라이언트가 프록시하는 호스팅 백엔드가 MCP 서버가 실제로 호출하는 대상이므로 mba_live_ 키가 여전히 적용됩니다.

도구 카탈로그

네 가지 Basket AI 에이전트 역할과 두 가지 운영 그룹으로 구성된 19개 도구입니다. 마켓플레이스 열은 도구가 호출하는 라우트를 제공하는 백엔드를 나타냅니다. 이는 이 서버가 현재 도달할 수 있는 백엔드와는 다릅니다. 위의 "플랫폼 적용 범위"를 참조하세요. "전체 5개"는 Shopify, BigCommerce, WooCommerce, Magento, OroCommerce를 의미합니다.

디스커버리

번들

이 도구들은 /recommendations에서 모든 것을 파생합니다(서버가 번들/점수 로직을 클라이언트 측에서 구성). 따라서 추가 백엔드 라우트가 필요 없으며 어디서나 작동합니다.

인사이트

또한 /recommendations에서 파생되므로 어디서나 사용할 수 있습니다.

재입고 + 예측

판매자 운영

이 도구들은 현재 BigCommerce에서 제공되는 Bearer /api/v1 라우트를 호출합니다. Shopify는 기회, 드리프트, 주간 계획을 /api/v1 라우트 대신 내장된 관리자 뷰를 통해 제공하므로, 이 도구들은 BigCommerce 백엔드를 대상으로 실행됩니다. 유일한 예외는 /explain-opportunity로, 현재 BigCommerce와 Shopify에서 제공됩니다. /explain-drift는 여전히 BigCommerce 전용입니다. 이 도구들은 해당 라우트가 없는 플랫폼에서 깔끔한 업스트림 오류를 표시합니다.

고급 마이닝

도구별 예시 프롬프트

서버를 연결한 후 이 중 아무거나 Claude Desktop / Claude Code / Cursor 채팅에 붙여넣으세요.

• get_recommendations: "marketbasketanalysis를 사용하여 고객들이 짐 백팩(제품 8472918765)과 함께 구매하는 항목을 찾아주세요."

• find_substitutes: "DSLR 바디가 품절되었습니다. 좋은 대체품은 무엇인가요?"

• get_rationale: "물병이 짐 백팩과 함께 추천되는 이유는 무엇인가요?"

• get_bundle_for_cart: "장바구니에 카메라 바디, 32GB SD 카드, 삼각대가 있습니다. 완전한 키트를 만들려면 무엇이 빠졌을까요?"

• propose_subscription_bundle: "고객 9876을 위한 월간 구독 키트를 만들어 주세요."

• score_cross_sell: "청소 키트가 DSLR 카메라 바디에 좋은 교차 판매 상품인가요?"

• score_return_risk: *"카메라 + 렌즈

  • 삼각대 + 가방 번들의 반품 위험은 얼마인가요?"*

• analyze_basket: "카메라 + 렌즈 + SD 카드 + 가방을 번들로 구성하려고 합니다. 실제 고객 데이터에 기반할 때 강력한 번들인가요?"

• predict_reorder: "Acme Corp(고객 7654321)은 이번 주에 무엇을 재주문할 예정인가요?"

• forecast_bundle: "번들 b-camera-kit를 향후 12주간 예측하고 구매 수량을 추천해 주세요."

• get_weekly_plan: "내 주간 계획은 무엇인가요?"

• execute_weekly_plan_action: "내 주간 계획의 액션 a-42를 실행하세요, 확인했습니다."

• get_opportunities: "제안된 상위 3개 기회를 보여주세요."

• explain_opportunity: "기회 opp-17이 왜 좋은 교차 판매인가요?"

• triage_opportunity: "기회 opp-17을 활성화하세요, 확인했습니다."

• get_drift_alerts: "내 규칙 중 드리프트된 것이 있나요?"

• explain_drift: "드리프트 알림 alert-7의 쌍은 왜 드리프트되었나요?"

• get_forecast_alerts: "어떤 번들이 품절 위험에 있나요?"

• mine_hui_itemsets: "이 90일 주문 페이로드에서 상위 20개 고효용 아이템셋을 마이닝하세요." (Plus / Enterprise 요금제)

도구별 상세 문서는 cookbook에 있습니다.

환경 변수

개발

git clone https://github.com/48x-ai/marketbasketanalysis-mcp
cd marketbasketanalysis-mcp
npm install
npm run typecheck
npm test
npm run dev    # tsx-based local run
npm run build  # emit ./dist

새 도구 추가

각 도구는 src/tools/ 아래에 있는 독립 모듈입니다. 추가하려면:

1. definition 및 handler를 내보내는 src/tools/myNewTool.ts를 생성합니다. 단순 GET의 경우 src/tools/getRecommendations.ts의 구조를, 확인 게이트가 있는 POST의 경우 src/tools/triageOpportunity.ts의 구조를 따르세요.

2. src/tools/index.ts에서 모듈을 가져와 allModules 배열에 추가하여 등록합니다.

3. src/tools/myNewTool.test.ts에 테스트를 추가합니다. 누락 키 응답, 정상 경로, 그리고 최소 하나의 업스트림 오류 경로를 포함하세요. src/tools/findSubstitutes.test.ts를 따르세요.

4. 위 표와 dist/mcp/smithery.yaml에 문서화합니다.

배포 산출물

모노레포 루트의 dist/mcp/ 디렉터리에는 설치 샘플(Claude Desktop, Cursor, Windsurf), Smithery YAML, 그리고 Anthropic 마켓플레이스 제출 콘텐츠가 들어 있습니다. 전체 레이아웃은 dist/mcp/README.md를 참조하세요.

게시

package.json에서 버전을 올리고(server.json 및 src/index.ts를 동기화 상태로 유지), main에 병합한 다음 mcp-v$VERSION 태그를 만들고 푸시합니다. 워크플로는 타입체크, 테스트, 빌드, 태그/버전 일치 확인을 실행한 후 NPM_TOKEN 저장소 시크릿을 사용해 npm publish --access public --provenance를 실행합니다. 복구 실행을 위해 workflow_dispatch 수동 트리거를 사용할 수 있습니다.

일회성 NPM_TOKEN 설정과 CI 없는 수동 게시 폴백을 포함한 전체 운영자 체크리스트는 docs/RELEASE.md에 있습니다.

문제 해결

더 자세한 진단은 dist/mcp/ 아래의 각 IDE별 설정 문서를 참조하세요.

라이선스

UNLICENSED, proprietary.