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.

Related MCP server: Taobao Sourcing Assistant

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

Tools

Output format

Tools return TOON (Token-Oriented Object Notation) rather than JSON. These payloads are mostly uniform arrays — products, reviews, cart items, orders — and TOON states the keys once in a header instead of repeating them on every element:

items[2]{productName,price,quantity}:
  에어팟 프로 3,369000,1
  충전 케이스,8900,2

That cart is 56% smaller than the equivalent JSON. Savings shrink as rows get more string-heavy: a real 60-product search result is only ~18% smaller, because it is dominated by long product and image URLs that no encoding can compress. The server advertises the format in its MCP instructions, so the model knows how to read it. Set COUPANG_MCP_FORMAT=json to get JSON back.

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

Troubleshooting

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