Universal Shopping Agent MCP Server

A Model Context Protocol (MCP) server that acts as an intelligent shopping assistant, using Google Gemini AI to analyze shopping intent and automate product searches across multiple e-commerce platforms.

Features

• AI-Powered Intent Analysis: Uses Google Gemini to extract structured shopping intent from natural language queries

• Multi-Platform Support: Searches across Amazon, Flipkart, and Myntra with country-specific domains

• Smart Search Optimization: Generates optimized search terms based on analyzed requirements

• Automated Browsing: Uses Playwright to automatically open browsers and perform searches

• Budget & Feature Filtering: Extracts and applies budget constraints and specific features

Related MCP server: Amazon MCP Server

Supported Platforms & Countries

• Amazon: IN (India)

• Myntra: IN (India)

Prerequisites

• Python 3.9+

• uv (The ultra-fast Python package and project manager)

• Claude Desktop App

• Google Gemini API Key

Installation & Setup

1. Navigate to the project directory:

   cd /path/to/this/folder

2. Initialize the project and create a virtual environment:

   uv init universal-shopping-agent
   uv venv

3. Create a .env file with your Gemini API key:

   GEMINI_API_KEY=your_gemini_api_key_here

4. Install the dependencies from the provided requirements.txt:

   uv add -r requirements.txt

5. Install the Playwright browser:

   playwright install chromium

Running the Server

To test and run the MCP server locally, use:

uv run --with "mcp[cli]" mcp run main.py

If it runs without errors, you are ready to connect it to Claude.

Connecting to Claude Desktop

1. Open Claude Desktop.

2. Go to Settings -> Developer -> Edit MCP Server Configuration. This will open the claude_desktop_config.json file.

3. Add a new configuration for this server. Replace the paths with the absolute paths on your system.

{
  "mcpServers": {
    "universal-shopping-agent": {
      "command": "/path/to/your/uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/universal-shopping-agent",
        "python",
        "main.py"
      ]
    }
  }
}

• command: The absolute path to your uv installation. Find it by running which uv in your terminal.

• args[3] (--directory): The absolute path to this project folder.

4. Save the file and restart Claude Desktop.

Usage Examples

Once configured, you can ask Claude shopping-related questions like:

• "My father needs a new smartphone under ₹20,000 with good battery life and clear video calls. Can you find recommendations on Amazon India?"

• "I need a college laptop under 40k that can handle online classes and light coding. Search across Indian e-commerce sites."

• "Find wireless earbuds under ₹5,000 with good sound quality and 20+ hours battery on Amazon."

Claude will:

1. Use Gemini AI to analyze your shopping intent

2. Ask for permission to connect to the shopping agent

3. Open a Chromium browser to perform the search on the appropriate platform

4. Return the search results and intent analysis

How It Works

1. Intent Analysis: Gemini AI extracts structured information from your query (category, budget, features, etc.)

2. Search Optimization: Generates the best search terms for e-commerce platforms

3. Automated Browsing: Opens amazon platform and performs the search automatically

Troubleshooting

• Gemini API Errors: Ensure your GEMINI_API_KEY is set correctly in the .env file

• Browser Issues: Make sure Playwright Chromium is installed: playwright install chromium

• Platform Errors: E-commerce websites frequently change their HTML structure; selectors may need updating

• Connection Issues: Verify all paths in your Claude MCP configuration are absolute paths

Important Notes

• The server opens a visible browser window (headless=False) to show you the search results

• Some platforms may show login popups; the code handles common ones like Flipkart's

• For clothing items, the agent automatically prefers Myntra over Amazon in India

• Always check the actual search results on the platform for the most current prices and availability

Example Output

When you ask about smartphones under ₹20,000, Claude will return:

• Structured intent analysis from Gemini

• Optimized search terms used

• Platform where the search was performed

• Confirmation that the browser was opened with your search

Note: This tool is for educational and personal use. Always verify product details and prices on the actual e-commerce platforms before making purchases.