Universal Shopping Agent 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

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.