coupang-browser-mcp

English · 한국어

Personal-use MCP server that searches Coupang through your own Chrome browser (CDP). No API key, no Partners account — and it can see what the official API can't: ratings, review text, your orders, your cart.

⚠️ Read this first

• This is a personal tool, not a service. It remote-controls the Chrome you launched, logged in as you, on your IP. Nothing is hosted, collected, or redistributed.
• It does not bypass bot protection — it drives a real browser session you own.
• Coupang's ToS may restrict automation tools; use at your own responsibility. Do not use for bulk or commercial data collection.
• Coupang markup changes can break extraction — use the built-in debug_page_structure tool to diagnose and update.
• Payment is never automated. proceed_to_checkout stops at the order sheet; the final pay click is always yours.
• Unofficial project — not affiliated with Coupang.

Quick Start

1. Launch Chrome with remote debugging (quit Chrome completely first):

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

Log into coupang.com in that Chrome if you want order/cart tools.

Don't want a browser window in your face? (macOS) Use the bundled wrapper instead of step 1 — it starts a separate Chrome on its own profile (port 9223), hides its window, and keeps it hidden. Point your MCP client at run-mcp-hidden.sh instead of npx coupang-browser-mcp:

claude mcp add coupang-browser -- \
  "$(npm root -g)/coupang-browser-mcp/scripts/run-mcp-hidden.sh"

Headless Chrome is not used: Coupang serves "Access Denied" to it, and this project does not evade bot detection. The window is real, just hidden. Run scripts/show-chrome.sh to bring it back for login or checkout (rm ~/.coupang-chrome/keep-visible re-hides it).

2. Add the server to your MCP client:

claude mcp add coupang-browser -- npx -y coupang-browser-mcp

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "coupang-browser": { "command": "npx", "args": ["-y", "coupang-browser-mcp"] }
  }
}

Add to ~/.codex/config.toml:

[mcp_servers.coupang-browser]
command = "npx"
args = ["-y", "coupang-browser-mcp"]

Add to opencode.json (project) or ~/.config/opencode/opencode.json (global):

{
  "mcp": {
    "coupang-browser": {
      "type": "local",
      "command": ["npx", "-y", "coupang-browser-mcp"],
      "enabled": true
    }
  }
}

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global), or via Settings → MCP → Add new global MCP server:

{
  "mcpServers": {
    "coupang-browser": { "command": "npx", "args": ["-y", "coupang-browser-mcp"] }
  }
}

Architecture

┌─────────────────┐  stdio (JSON-RPC)  ┌──────────────────────┐
│   MCP client    │◄──────────────────►│  coupang-browser-mcp │
│  (Claude Code,  │                    │                      │
│   Cursor, ...)  │                    │  index.ts   9 tools  │
└─────────────────┘                    │  throttle.ts ≥5s gap │
                                       │  extract.ts  parsers │
                                       └──────────┬───────────┘
                                                  │ CDP (playwright-core)
                                                  │ localhost:9222
                                                  ▼
                                       ┌──────────────────────┐
                                       │   YOUR own Chrome    │
                                       │  (your session, your │
                                       │   login, your IP)    │
                                       └──────────┬───────────┘
                                                  │ real browser traffic
                                                  ▼
                                       ┌──────────────────────┐
                                       │     coupang.com      │
                                       │  search / product /  │
                                       │  reviews / orders /  │
                                       │        cart          │
                                       └──────────────────────┘

Per tool call:  navigate the shared tab → extract (embedded JSON ▸ DOM fallback) → reset to about:blank
Calls are serialized over ONE reused tab: opening a tab makes macOS un-hide Chrome,
which would pop a window on every call.

Example Prompts

| You say | Tool used | |---|---| | "쿠팡에서 에어팟 검색해줘" | search_products | | "이 상품 평점이랑 리뷰 수 알려줘" | get_product_detail | | "이 상품 리뷰 좀 읽어줘" | get_product_reviews | | "내 주문 배송 어디까지 왔어?" | get_my_orders | | "장바구니에 뭐 들어있지?" | get_cart | | "이거 장바구니에 담아줘" | add_to_cart (preview → confirm) | | "주문할게, 결제 페이지 열어줘" | proceed_to_checkout (stops before payment) |

Tools

| Tool | Parameters | Description | |---|---|---| | search_products | keyword*, limit (≤36), rocketOnly, sortBy | Extract products from the search page (embedded JSON first, DOM fallback) | | get_product_detail | url* | Price, rating, review count from a product page — data the official API can't provide | | get_product_reviews | url*, limit (≤10), maxTextLength | Individual reviews (author, date, rating, purchased option, text) — scrolls the lazy-loaded review section into view | | debug_page_structure | url* | Skeleton of embedded JSON blobs on a page — self-diagnosis when markup drifts | | get_my_orders | — | Order history + delivery status (read-only, needs login) | | get_cart | — | Cart contents (read-only, needs login) | | add_to_cart | url*, quantity, confirm | Two-step: preview first, executes only with confirm=true | | remove_from_cart | productName*, confirm | Two-step; removes only when exactly one item matches | | proceed_to_checkout | confirm | Two-step; on confirm=true opens the order sheet and stops — clicks only on the cart page, never a pay button, tab left open |

Safety model

1. Reads are free, writes confirm. Cart mutations and checkout return a preview and require an explicit confirm=true second call.
2. Money never moves automatically — and this is enforced, not just promised. openCheckout() clicks only while the URL is still cart.coupang.com, refuses any button whose label reads like payment (결제, 바로구매, pay), and once the order sheet is open it stops touching the page. No code path clicks a pay button.
3. Polite self-throttle: ≥5s between page loads, ≤60 loads/hour (configurable). There's no contractual limit here, so we impose our own.

Configuration

| Env var | Default | Description | |---|---|---| | COUPANG_CDP_URL | http://localhost:9222 | Chrome DevTools endpoint | | COUPANG_MIN_GAP_MS | 5000 | Minimum gap between page loads | | COUPANG_HOURLY_CEILING | 60 | Max page loads per hour |

Troubleshooting

| Symptom | Fix | |---|---| | "Chrome CDP에 연결할 수 없습니다" | Chrome isn't running with --remote-debugging-port=9222, or an older non-debug Chrome instance is holding the profile — quit Chrome fully and relaunch with the flag | | Browser context management is not supported | Stale debug instance — kill it and relaunch Chrome cleanly | | Empty results / "추출 실패" | Coupang markup changed — run debug_page_structure on the same URL and file an issue with its output | | "쿠팡 로그인이 필요합니다" | Log into coupang.com in the debug Chrome (order/cart tools only) | | A Chrome window pops up on every call | You're on an older version — 0.2.1 and earlier opened a new tab per call. Upgrade, and use run-mcp-hidden.sh if you want the window hidden entirely |

Development

npm install
npm run lint                      # eslint (type-checked)
npm test                          # extraction unit tests (no browser needed)
npm run build                     # tsc → dist/
npx tsx scripts/tool-output.ts    # live check → test-output/*.txt (uses your Chrome if running)

License

MIT