shop-mcp

A local Python MCP server that wraps browser automation for your own Amazon.in and Flipkart accounts — search, cart management, and guarded checkout.

⚠️ Read this before using it

1. Terms of Service. Both Amazon.in and Flipkart's ToS restrict automated / bot access. This tool is built for personal, low-volume use of your own account (the way you'd use a browser yourself, just orchestrated by an MCP client). Running it at scale, using it commercially, or hiding automation from the platform is a ToS violation and can get your account flagged or banned. That risk is yours to accept.

2. No password storage or replay. This project never stores or types your password. You log in manually (including any OTP/CAPTCHA) in a real browser window the first time; Playwright saves the resulting session (cookies + local storage) to sessions/<site>.json. All later tool calls reuse that session. When it expires, you just log in again.

3. Purchases are guarded, not prevented. place_order will not fire without a confirm_token produced by checkout_dry_run in the same session, and it enforces a price cap from config.py. Read the code in server.py before raising the cap or automating around the confirmation step — that guard is there for a reason.

4. Selectors will need maintenance. Amazon/Flipkart change their DOM often. The CSS/text selectors in browser/amazon.py and browser/flipkart.py are starting points, not guarantees — expect to inspect the live page (DevTools) and adjust selectors when something breaks.

5. Headed, not headless. Both sites detect and often block headless Chromium, especially at login/checkout. Everything here runs with a visible browser window (headless=False).

Related MCP server: browser-agent-mcp

Setup

python -m venv .venv
source .venv/bin/activate          # or .venv\Scripts\activate on Windows
pip install -r requirements.txt
playwright install chromium        # downloads Chromium browser binary (~180MB)

Note: playwright install chromium is required — it downloads the browser binary that Playwright uses for automation. This is separate from the Python package and won't work without it.

First-time login (per site)

python -m browser.login amazon
python -m browser.login flipkart

A browser window opens. Log in normally, complete any OTP/CAPTCHA, wait until you're on the homepage/account page, then return to the terminal and press Enter. The session is saved and reused by the MCP server.

Running the MCP server

python server.py

This starts the server using stdio transport (the standard way local MCP servers communicate with clients). You don't interact with it directly — your MCP client connects to it.

MCP Client Configuration

An example config file is provided at mcp-config-example.json. Copy and adapt it for your client. Replace paths with your actual absolute paths.

Claude Desktop

Edit claude_desktop_config.json (usually at %APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on 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 in your workspace (or ~/.kiro/settings/mcp.json for global):

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

Generic MCP Client (stdio)

Any MCP client that supports stdio transport can connect. The key settings:

Linux / macOS paths

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

Note: Always use the Python from your virtual environment (.venv) so all dependencies are available. Setting PYTHONUNBUFFERED=1 ensures tool output streams without buffering delays.

Tools exposed

Config

Edit config.py:

• MAX_ORDER_TOTAL_INR — hard ceiling; place_order refuses above this regardless of what's asked.

• REQUIRE_CONFIRM_TOKEN — leave True. This ties every purchase to a specific dry-run summary so nothing can be placed "blind."