shop-mcp

A local MCP server for personal shopping automation on Amazon.in & Flipkart
Search products, compare prices, manage cart, and place orders — all through your AI assistant with safety guards built in.

Quick Start • Architecture • Tools • Safety Guards • Client Config

---

How It Works

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

---

Key Features

Feature	Description
Price Comparison	Search the same product on both platforms and compare prices instantly
Cart Management	View, add to cart across Amazon.in and Flipkart
Guarded Checkout	Orders require a dry-run summary + confirmation token + price cap
No Password Storage	You log in manually once; only session cookies are saved
Headed Browser	Visible Chromium window — no stealth, no detection issues
MCP Standard	Works with any MCP-compatible AI client via stdio transport

---

Quick Start

# 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

Note: playwright install chromium downloads the Chromium binary that Playwright controls. This is separate from the Python package and required for the server to work.

---

Tools

Tool	Effect	Risk Level
search_product	Search a site for products	Read-only
get_product_details	Get price, title, availability for a product URL	Read-only
view_cart	List current cart contents	Read-only
get_order_status	Look up an existing order by ID	Read-only
add_to_cart	Add a product to the cart	Reversible
checkout_dry_run	Load checkout summary WITHOUT submitting	Read-only
place_order	Submit the order	Irreversible — guarded

---

Safety Guards

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)

Configure in config.py:

Setting	Default	Purpose
MAX_ORDER_TOTAL_INR	3000	Hard price ceiling per order
REQUIRE_CONFIRM_TOKEN	True	Forces dry-run before every purchase
CONFIRM_TOKEN_TTL_SECONDS	300	Token expiry (forces fresh price check)

---

MCP Client Config

Example config file: mcp-config-example.json

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

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

Kiro IDE

Add to .kiro/settings/mcp.json:

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

Linux / macOS

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

Always use the Python from your .venv so all dependencies are available.

---

Project Structure

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

---

Important Notes

Terms of Service	Amazon.in and Flipkart restrict bot access. This is for personal, low-volume use of your own account only.
Selectors Break	Both sites change their DOM frequently. Expect to update CSS selectors in browser/amazon.py and browser/flipkart.py when things stop working.
Headed Mode	Both sites detect headless browsers. Everything runs with a visible Chromium window (headless=False).
Session Expiry	When cookies expire, re-run python -m browser.login <site> to refresh.

---

Tech Stack

Component	Technology
Server Framework	MCP (Model Context Protocol) via fastmcp
Browser Automation	Playwright (Chromium)
Language	Python 3.10+
Transport	stdio (local server)

---

License

MIT License. See LICENSE for details.

---

Built for personal use. Use responsibly. Your account, your risk.