shop-mcp

graph LR
    A[AI Assistant<br/>Claude / Open AI / Kiro / Any AI Chat or LLM Model] -->|MCP Protocol<br/>stdio| B[shop-mcp<br/>Server]
    B -->|Playwright<br/>Browser Automation| C[Amazon.in]
    B -->|Playwright<br/>Browser Automation| D[Flipkart]

    B --- E[Saved Sessions<br/>cookies only<br/>no passwords]

    style A fill:#4A90D9,color:#fff
    style B fill:#2ECC71,color:#fff
    style C fill:#FF9900,color:#fff
    style D fill:#F7D02C,color:#000
    style E fill:#95A5A6,color:#fff

flowchart LR
    AI["🤖 YOUR AI ASSISTANT\nClaude Desktop · Kiro · Any MCP Client"]

    subgraph SERVER["🖥️ shop-mcp SERVER"]
        direction TB
        RO["📖 Read-Only\nsearch_product\nview_cart\nget_product_details\nget_order_status"]
        MU["✏️ Mutations\nadd_to_cart"]
        GC["🔐 Guarded Checkout\ncheckout_dry_run\nplace_order\nToken + ₹3000 cap\n5 min expiry"]
    end

    subgraph SITES["🌐 Shopping Platforms"]
        direction TB
        AMZ["🟠 Amazon.in\nSession cookies\nManual login once"]
        FK["🔵 Flipkart\nSession cookies\nManual login once"]
    end

    AI -->|"MCP Protocol\nstdio"| SERVER
    SERVER -->|"Playwright\nChromium"| SITES

    style AI fill:#1a73e8,stroke:#0d47a1,stroke-width:3px,color:#fff
    style SERVER fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#2e7d32
    style RO fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20
    style MU fill:#fff9c4,stroke:#f9a825,stroke-width:2px,color:#e65100
    style GC fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#b71c1c
    style SITES fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px,color:#6a1b9a
    style AMZ fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#bf360c
    style FK fill:#e8eaf6,stroke:#283593,stroke-width:2px,color:#1a237e

# 1. Clone & setup
git clone https://github.com/detushar/shop-mcp.git
cd shop-mcp
python -m venv .venv
.venv\Scripts\activate              # or source .venv/bin/activate on Linux/macOS

# 2. Install dependencies
pip install -r requirements.txt
playwright install chromium          # downloads browser binary (~180MB)

# 3. Login to sites (one-time, manual)
python -m browser.login amazon
python -m browser.login flipkart

# 4. Run the MCP server
python server.py

place_order() will REFUSE if:
  ✗ No checkout_dry_run() was called first
  ✗ confirm_token doesn't match the latest dry-run
  ✗ Token is older than 5 minutes (stale prices)
  ✗ Order total exceeds ₹3,000 (configurable cap)

{
  "mcpServers": {
    "shop-mcp": {
      "command": "C:\\path\\to\\shop-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\shop-mcp\\server.py"],
      "env": { "PYTHONUNBUFFERED": "1" }
    }
  }
}

{
  "mcpServers": {
    "shop-mcp": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "D:\\path\\to\\shop-mcp",
      "env": { "PYTHONUNBUFFERED": "1" },
      "disabled": false
    }
  }
}

{
  "mcpServers": {
    "shop-mcp": {
      "command": "/path/to/shop-mcp/.venv/bin/python",
      "args": ["/path/to/shop-mcp/server.py"],
      "env": { "PYTHONUNBUFFERED": "1" }
    }
  }
}

shop-mcp/
├── server.py               # MCP server — tool definitions & checkout guards
├── config.py               # Safety settings, timeouts, site URLs
├── requirements.txt        # Python dependencies
├── mcp-config-example.json # Client configuration template
├── browser/
│   ├── base.py             # Playwright session management (cookies, context)
│   ├── amazon.py           # Amazon.in browser actions (search, cart, checkout)
│   ├── flipkart.py         # Flipkart browser actions
│   └── login.py            # Manual login helper (opens browser for you)
└── sessions/               # Auto-created, .gitignored — stores login cookies