coupangctl

내 쿠팡 주문을 내 컴퓨터에 동기화하고, CLI와 AI로 검색·분석하는 로컬 우선 오픈소스 도구입니다.

한눈에 보기

• 내 주문 기록 — 전체 주문을 중단 후 이어받을 수 있게 동기화하고 SQLite에 정규화합니다.

• 내 소비 분석 — 월별 지출, 취소·반품, 구매 시간대, 배송 소요, 반복 구매, 카테고리를 계산합니다.

• 공유용 리캡 — 근거와 표본을 함께 보여주는 독립형 HTML 리캡과 16가지 쇼핑 유형을 만듭니다.

• 자연어 상품 탐색 — AI가 자연어 조건을 타입이 있는 검색·상세 조회로 바꿉니다.

• CLI와 MCP — 같은 typed core를 터미널과 MCP 클라이언트에서 함께 사용합니다.

• 구매 직전까지만 — 장바구니 추가는 명시적으로 확인한 한 상품만 가능하고, 주문·결제는 경계 밖입니다.

Related MCP server: ECommerce MCP Server

쿠팡 파트너스 고지

쿠팡 홈 열기

이 링크를 통해 구매하면 쿠팡 파트너스 활동의 일환으로 일정액의 수수료를 제공받습니다. 제휴 링크 자체로 구매자에게 별도 수수료가 부과되지는 않으며, 상품 가격과 혜택은 쿠팡의 최종 화면에서 확인해야 합니다. 프로젝트 운영자의 본인 구매는 수익 인정 대상이 아닙니다.

3분 빠른 시작

현재는 소스 빌드를 기준으로 합니다. Go 1.26 이상과 설치된 Chrome 계열 브라우저가 필요합니다.

git clone https://github.com/JungHoonGhae/coupang-ctl.git
cd coupang-ctl
go build -o ./bin/coupangctl ./cmd/coupangctl

./bin/coupangctl doctor
./bin/coupangctl auth login
./bin/coupangctl orders sync
./bin/coupangctl orders recap --output ./shopping-recap.html

auth login은 QR 로그인을 기본으로 엽니다. 휴대폰에서 승인하면 세션을 전용 브라우저 프로필에 연결하고, 이후 읽기는 headless 우선으로 실행합니다. 모든 CLI 명령은 문서화된 JSON 객체를 출력합니다.

무엇을 할 수 있나요?

현재 구현 상태와 다음 순서는 ROADMAP.md와 coupangctl capabilities에서 확인할 수 있습니다.

주문 분석과 리캡

coupangctl orders list --limit 20
coupangctl orders spend --from 2026-01-01
coupangctl orders stats --from 2026-01-01
coupangctl orders insights
coupangctl orders products
coupangctl orders categories --max-products 25
coupangctl orders reorder --limit 20
coupangctl orders recap --output ./shopping-recap.html

분석값은 세 가지 출처를 구분합니다.

• 관찰값: 쿠팡 화면이나 구조화 응답에서 직접 읽은 값

• 계산값: 관찰값을 명시적인 규칙으로 합산·분류한 값

• 추론값: 원천에 없는 정보를 휴리스틱으로 추정한 값

공개형 리캡은 기간, 표본 수, 분모, 제외 규칙을 함께 보여줍니다. 카테고리는 상품명으로 억지 매핑하지 않고 쿠팡 상품 페이지의 가변 길이 BreadcrumbList만 사용하며, 확인하지 못한 상품은 unknown으로 남깁니다.

orders spend는 전체 원장 합계와 함께 product_purchases, membership_fees, unclassified를 분리합니다. 명시적인 멤버십 결제를 상품 구매나 연속 구매 기록에 섞지 않습니다.

자연어로 상품 찾기

CLI는 관찰 가능한 조건을 그대로 받습니다.

coupangctl products search \
  --query '후기 좋은 10만원 아래 맥북 허브' \
  --max-price 100000 \
  --min-rating 4.5 \
  --exclude-sponsored

coupangctl products search \
  --query '게이밍 데스크탑 16GB 512GB' \
  --min-memory-gb 16 \
  --min-storage-gb 512 \
  --exclude-used \
  --sort sales

MCP를 쓰면 AI가 “후기 좋은 10만 원 아래 맥북 허브, 광고 제외” 같은 요청을 products_search의 typed filter로 바꿉니다. 선택한 후보는 product_inspect로 가격, 배송, 이미지, 상세 내용, 관찰된 쿠폰·카드 혜택, 평점과 정제된 후기를 확인할 수 있습니다.

정렬 의미는 섞지 않습니다.

• coupang_ranking: 쿠팡 랭킹순

• sales: 판매량순

• latest: 최신순

• price_asc, price_desc: 가격순

• 평점·후기 수: 현재 관찰한 카드 집합의 로컬 정렬

상품 페이지 단위 후기 수를 옵션별 판매량처럼 표현하지 않습니다. 상품 가격과 프로모션은 바뀔 수 있으므로 최종 쿠팡 화면에서 다시 확인해야 합니다.

장바구니 추가

coupangctl products cart-add \
  --product-id ID \
  --vendor-item-id ID \
  --quantity 1 \
  --confirm-add-to-cart

검색에서 관찰한 정확한 vendor_item_id와 --confirm-add-to-cart가 모두 필요합니다. 결과를 검증하지 못하면 자동 재시도하지 않으며, 구매·주문·결제 버튼으로 이동하지 않습니다.

MCP 연결

표준 stdio MCP 설정은 다음과 같습니다. command에는 빌드한 바이너리의 절대경로를 권장합니다.

{
  "mcpServers": {
    "coupangctl": {
      "command": "/absolute/path/to/coupangctl",
      "args": ["mcp"]
    }
  }
}

대표 도구:

• auth_status, account_benefits

• orders_sync, orders_list, orders_spend, orders_stats

• orders_insights, orders_product_insights, orders_reorder_candidates

• orders_export, orders_enrich_categories

• products_search, product_inspect, cart_add

읽기 도구와 변경 도구는 MCP annotation과 입력 타입에서 구분됩니다. cart_add만 되돌릴 수 있는 외부 변경이며 별도 확인값을 요구합니다.

로그인 방식

로그인은 headed 브라우저에서만 진행합니다. 실측상 보호된 로그인 진입점은 진짜 headless Chrome을 거부할 수 있습니다. 로그인 뒤의 검증과 읽기는 headless 우선이며, 환경이 거부할 때만 설치된 브라우저의 headed 읽기로 한 번 재시도할 수 있습니다.

--link 출력은 짧게 살아 있는 인증 정보이므로 로그로 리디렉션하지 마세요. OTP, 쿠키, QR 링크는 JSON·세션 파일·테스트 fixture·오류 메시지에 넣지 않습니다.

데이터 저장과 개인정보

상태 경로:

• macOS: ~/Library/Application Support/coupangctl

• Linux: $XDG_STATE_HOME/coupangctl 또는 ~/.local/state/coupangctl

• Windows: %LOCALAPPDATA%\\coupangctl

테스트 격리는 COUPANGCTL_STATE_DIR에 절대경로를 지정합니다. 브라우저 자동 탐색이 실패할 때만 COUPANGCTL_BROWSER_PATH를 사용합니다.

역공학한 읽기 엔드포인트는 불안정할 수 있습니다. 응답 형식은 좁은 adapter 뒤에 두고, 실패를 우회 성공으로 표현하지 않습니다. 테스트와 문서는 합성 fixture와 가린 네트워크 메타데이터만 사용합니다.

구조

cmd/coupangctl
  ├─ CLI adapter ─────┐
  │                   ├─ typed services ─┬─ native browser adapters
  └─ MCP stdio adapter┘                  └─ SQLite repository

typed core, CLI adapter, MCP adapter를 분리합니다. CLI와 MCP가 각자 브라우저 로직을 갖지 않으며, 운영 코드에는 Playwright·Orca·특정 에이전트 런타임 의존성이 없습니다. 비공개·역공학 응답은 좁은 adapter에 격리하므로, 나중에 공식 API가 생겨도 core와 두 인터페이스를 유지할 수 있습니다.

TypeScript 코드는 프로토콜 조사용 probe에만 남아 있고 배포 바이너리의 런타임 의존성이 아닙니다.

개발

go test ./...
go vet ./...
npm run typecheck
go build ./cmd/coupangctl

새 지표는 typed response, provenance, 분모, 표본 수, 누락 동작, 합성 테스트, 리캡 문구가 모두 맞을 때만 완료로 봅니다. 자세한 원칙은 PRODUCT_PRINCIPLES.md를 참고하세요.

파트너스 링크 비활성화

공식 쿠팡 파트너스 API 키가 설정되면 원본 쿠팡 URL과 별도로 affiliate_url을 반환할 수 있습니다. 사용자에게 제휴 링크를 강제하지 않습니다.

export COUPANGCTL_AFFILIATE_DISABLED=true
coupangctl products inspect --product-id ID --no-affiliate

개발용 키는 Doppler의 cli-mcp-lab/dev_coupang 설정에서만 관리합니다. 저장소에는 COUPANG_PARTNERS_ACCESS_KEY, COUPANG_PARTNERS_SECRET_KEY, 선택적인 COUPANG_PARTNERS_SUB_ID라는 이름만 문서화하며 값은 넣지 않습니다.

문서

• ROADMAP.md — 기능 우선순위와 구현 상태

• HANDOFF.md — 검증된 동작과 아키텍처 결정

• TYPE_SYSTEM.md — 네 가지 행동 축과 16개 유형

• PRODUCT_PRINCIPLES.md — 증거·개인정보·완료 기준

• research/endpoint-catalog.md — 가린 비공개 route 목록

• research/README_BENCHMARKS.md — 인기 CLI·MCP 저장소를 참고한 README 설계 근거

기여

이슈와 Pull Request를 환영합니다. 버그를 재현할 때는 실제 주문 응답, 쿠키, OTP, 전화번호, 계정 식별자를 첨부하지 말고 합성 데이터나 가린 메타데이터를 사용해 주세요. PR을 보내기 전에는 위의 개발 명령 네 가지를 모두 통과시켜 주세요.

라이선스

MIT

coupangctl은 쿠팡의 공식 제품이 아니며, 쿠팡 및 관련 상표는 각 권리자에게 귀속됩니다.