Amazon India Product Research MCP

Un servidor MCP (Model Context Protocol) que convierte Claude Desktop en un asistente de investigación de productos para vendedores principiantes de Amazon India. Puntúa las oportunidades de producto, estima la demanda, evalúa la competencia, calcula la rentabilidad real de Amazon India, planifica el aprovisionamiento, extrae las quejas de los clientes, investiga palabras clave y redacta un listado completo.

Se ejecuta a través de stdio, por lo que se conecta directamente a Claude Desktop.

¿Nuevo aquí? Empieza con la Guía de configuración y ejecución — instalación paso a paso, verificación y configuración de Claude Desktop, con una sección de resolución de problemas. Para datos en vivo, consulta la Guía de datos en vivo y extracción.

24 herramientas. Funciona sin claves API — en modo demo sin conexión, o con datos reales en vivo de fuentes gratuitas (Google Trends, DuckDuckGo, páginas públicas de amazon.in).

Descripción general del proyecto

El servidor se basa en un perfil de vendedor:

Cada herramienta puntúa los productos según estos criterios y penaliza lo que hunde a los nuevos vendedores: productos de marca, riesgo de falsificación, artículos frágiles, pilas, electrónica compleja, perecederos, productos de temporada, tallas de ropa, artículos pesados y categorías dominadas por marcas fuertes.

La integridad de los datos es lo primero

Este proyecto se niega a inventar datos del mercado. Cada salida significativa lleva source, data_type, confidence y last_updated, donde data_type es uno de Live, Verified, Estimated, Historical o Demo.

• Los datos de demostración siempre se etiquetan como Demo y nunca se presentan como datos reales de Amazon.

• Las cifras de demanda y ventas mensuales son estimaciones modeladas, nunca ventas reales de Amazon.

• Las tarifas de Amazon provienen de un calendario configurable; el incluido está etiquetado como Estimated.

• Los proveedores nunca se inventan. Sin una API de proveedores, search_suppliers devuelve una lista de proveedores vacía junto con canales de aprovisionamiento reales y públicos que puedes verificar por ti mismo.

• Ninguna herramienta garantiza beneficios o ventas garantizadas.

Características

• 20 herramientas MCP que cubren todo el flujo de trabajo del vendedor: descubrimiento, demanda, competencia, dinero, listado, aprovisionamiento y datos en vivo

• Datos en vivo gratuitos, sin claves API: interés de búsqueda de Google Trends, búsqueda web de DuckDuckGo y páginas públicas de amazon.in, incluidas las insignias de "comprados en el último mes"

• Estimación de ingresos y ventas a partir de curvas BSR o de las propias insignias de compra de Amazon, siempre como un rango con el método indicado

• Detección de nuevos vendedores: qué competidores tienen pocas reseñas y cuáles de ellos ya superan las 300+ unidades al mes — la señal más fuerte de que una página es ganable

• Puntuación de perennidad a partir de hasta 5 años de interés de búsqueda real, para que evites el stock muerto estacional

• Planificación de anuncios de Amazon: ACOS de equilibrio, escalas de ofertas por tipo de concordancia, asignación de palabras clave de concordancia, estructura de campañas y palabras clave negativas, todo derivado de tu propia economía unitaria en lugar de consejos genéricos

• Puntuación de oportunidad ponderada de 0 a 100, además de selección por lotes de hasta 15 ideas a la vez

• Cálculo de tarifas de Amazon India: referencia, cierre, FBA / Easy Ship / Self Ship, GST sobre tarifas, reserva de devoluciones, punto de equilibrio y precio recomendado

• Planificación del lanzamiento: cantidad de pedido, distribución del presupuesto, presupuesto publicitario, punto de reabastecimiento, retorno de la inversión

• Agrupación de quejas de reseñas con soluciones concretas a nivel de proveedor

• Investigación de palabras clave, borrador de listado y un plan de imágenes de siete huecos

• Extracción conforme a las normas: robots.txt, lista blanca, retardo de rastreo, presupuesto de páginas y una parada firme ante los retos de bots — sin eludir la protección antibots

• Historial de investigación almacenado en SQLite o PostgreSQL

• Modo demo completo: todo funciona sin conexión, de forma determinista

Arquitectura

amazon-india-seller-mcp/
│
├── amazon_india_seller_mcp/      # the installable package
│   ├── __init__.py
│   ├── __main__.py               # python -m amazon_india_seller_mcp
│   └── server.py                 # MCP entry point (stdio transport) - wiring only
│
├── server.py                     # compatibility shim: python server.py still works
│
├── amazon_india_seller_mcp/tools/                        # MCP tool definitions - thin: validate, call service, shape result
│   ├── __init__.py               # ServiceBundle + error-handling decorator
│   ├── product_research.py       # research_product
│   ├── demand_analysis.py        # analyze_product_demand
│   ├── competition.py            # analyze_competition
│   ├── profit_calculator.py      # calculate_profitability
│   ├── supplier_search.py        # search_suppliers
│   ├── review_analysis.py        # analyze_reviews
│   ├── keyword_research.py       # research_keywords
│   ├── listing_generator.py      # generate_listing
│   ├── revenue_calculator.py     # calculate_revenue
│   ├── competitor_analysis.py    # analyze_competitors
│   ├── purchase_signals.py       # analyze_purchase_signals
│   ├── review_metrics.py         # analyze_review_metrics
│   ├── evergreen_analysis.py     # analyze_evergreen
│   ├── product_images.py         # analyze_product_images
│   ├── opportunity_finder.py     # find_product_opportunities
│   ├── launch_planner.py         # plan_product_launch
│   ├── ppc_keywords.py           # suggest_ppc_keywords
│   ├── ppc_bidding.py            # calculate_ppc_bids / plan_ppc_campaign
│   ├── web_search.py             # search_web
│   ├── amazon_scraper.py         # scrape_amazon_search / scrape_amazon_product / scraper_status
│   └── listing_scraper.py        # scrape_listing_details
│
├── amazon_india_seller_mcp/services/                     # All business logic
│   ├── __init__.py               # Data envelopes, errors, cache, opportunity scoring
│   ├── amazon_service.py         # Provider abstraction (demo / scraper / API), snapshots, risk, reviews, listings
│   ├── trends_service.py         # Demand, trend direction, seasonality, keywords, live Google Trends
│   ├── supplier_service.py       # Sourcing research (never fabricates suppliers)
│   ├── pricing_service.py        # Fees, profit, margin, ROI, break-even, recommended price
│   ├── revenue_service.py        # Units from BSR/badges, revenue, competitor stage, evergreen scoring
│   ├── search_service.py         # Web search (DuckDuckGo free, Brave/Serper/Tavily/Google CSE)
│   ├── browser_service.py        # Guardrailed fetching: allowlist, robots.txt, delay, budget, block detection
│   ├── scraper_service.py        # Amazon India page parsing (search, product, listing detail, reviews, bestsellers)
│   ├── ads_service.py            # Sponsored Products bid maths, keyword match types, campaign structure
│   └── security.py               # SSRF guards, log redaction, prompt-injection scanning, size caps
│
├── amazon_india_seller_mcp/database/                     # Research history
│   ├── __init__.py
│   └── models.py                 # SQLAlchemy models + session handling
│
├── amazon_india_seller_mcp/config/                       # Centralised settings
│   ├── __init__.py
│   └── settings.py               # Env-driven settings + configurable fee schedule
│
├── tests/
│   ├── __init__.py
│   ├── test_product_research.py
│   ├── test_demand_analysis.py
│   ├── test_competition.py
│   └── test_profit_calculator.py
│
├── docs/
│   ├── SETUP.md                  # full setup, run and troubleshooting guide
│   ├── SCRAPING.md               # live data sources, guardrails and compliance
│   ├── PROMPTS.md                # copy-paste prompt library for all 20 tools
│   └── check_connection.py       # MCP connection self-test
│
├── .env.example
├── mcp.json.example
├── LICENSE                       # MIT
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md                   # threat model and controls
├── CHANGELOG.md
├── .github/workflows/ci.yml      # tests on Python 3.11-3.13
├── pyproject.toml                # Dependencies, managed by uv
└── uv.lock

Reglas que sigue el código: server.py no contiene lógica de negocio, las herramientas no contienen lógica de negocio, los servicios la contienen toda.

Instalación

Requisitos: Python 3.11+ y uv. La Guía de configuración y ejecución cubre cada paso en detalle.

Úsalo sin clonar nada

uvx amazon-india-seller-mcp

Esa es toda la instalación. Apunta Claude Desktop a ello:

{
  "mcpServers": {
    "amazon-india-seller": {
      "command": "uvx",
      "args": ["amazon-india-seller-mcp"],
      "env": { "DEMO_MODE": "true" }
    }
  }
}

O instálalo en un entorno

uv tool install amazon-india-seller-mcp     # then run: amazon-india-seller-mcp
pip install amazon-india-seller-mcp         # works too

O trabaja desde una copia del código fuente (para desarrollo)

git clone https://github.com/Suriya-Ravichandran/amazon-india-seller-mcp.git
cd amazon-india-seller-mcp
uv sync --all-extras
uv run python -m amazon_india_seller_mcp

Los datos en vivo gratuitos necesitan las dependencias adicionales: uv sync --extra realtime --extra browser.

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# or via pip
python -m pip install uv

Entorno virtual

uv sync gestiona el entorno virtual por ti; ejecuta los comandos con uv run. Si prefieres activarlo manualmente:

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

Dependencias

Declaradas en pyproject.toml y fijadas en uv.lock:

mcp, pydantic, pydantic-settings, httpx, sqlalchemy, python-dotenv; pytest en el grupo de desarrollo.

Añade o cambia una dependencia con uv add <paquete> / uv remove <paquete> — nunca edites el archivo de bloqueo a mano.

Configuración del entorno

cp .env.example .env      # Windows: copy .env.example .env

Los secretos viven solo en .env, que está en gitignore. Nada está codificado en el código fuente.

Configuración de la base de datos

Las tablas se crean automáticamente al inicio. No hay que ejecutar nada a mano.

Desarrollo (por defecto): SQLite en ./amazon_product_mcp.db.

PostgreSQL:

DATABASE_URL=postgresql+psycopg://user:password@localhost:5432/amazon_mcp

Las columnas de carga JSON se asignan a JSONB en PostgreSQL y a JSON en SQLite automáticamente. Instala el controlador junto a ella: uv add psycopg[binary].

Modelos almacenados: ProductResearch, DemandAnalysis, CompetitionAnalysis, ProfitCalculation, SupplierResearch — cada uno conserva product_name, marketplace, research_data, data_source, data_type, confidence, created_at, updated_at.

El almacenamiento del historial es de mejor esfuerzo: si la base de datos no está disponible, las herramientas siguen funcionando y el error se registra en lugar de mostrarse.

Ejecutar el MCP

uvx amazon-india-seller-mcp              # installed
uv run python -m amazon_india_seller_mcp # from a checkout
uv run server.py                         # legacy path, still supported

El proceso habla el protocolo MCP a través de stdio, por lo que permanecerá en silencio esperando a un cliente — eso es un comportamiento correcto. Los registros van a stderr, manteniendo stdout limpio para el tráfico del protocolo. Detenlo con Ctrl+C.

Configuración de Claude Desktop

1. Abre el archivo de configuración de Claude Desktop:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Copia el bloque mcpServers de mcp.json.example en él, reemplazando las rutas con tus propias rutas absolutas:

{
  "mcpServers": {
    "amazon-product-research": {
      "command": "/ABSOLUTE/PATH/TO/amazon-india-seller-mcp/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/TO/amazon-india-seller-mcp/server.py"],
      "env": { "DEMO_MODE": "true" }
    }
  }
}

En Windows usa .venv\\Scripts\\python.exe y escapa las barras invertidas. También se incluye una variante uv --directory ... run server.py en el archivo de ejemplo.

3. Cierra y reinicia Claude Desktop por completo (ciérralo desde la bandeja/barra de menús; recargar la ventana no es suficiente).

4. Prueba la conexión: las herramientas aparecen en el menú de herramientas de Claude Desktop, y preguntar "Calcula el beneficio de un producto de 399 ₹ que cuesta 120 ₹" debería activar calculate_profitability.

Herramientas MCP disponibles

Descubrimiento

Demanda

Competencia

Dinero

Listado

Publicidad

Abastecimiento

Datos en vivo

Puntuación de oportunidad

Ejemplos de prompts

Find beginner-friendly Amazon India products under ₹20,000 investment.

Screen these ideas and rank them: sink strainer, cable organizer, spice rack.

Analyze the demand for silicone sink strainers on Amazon India.

Is a silicone sink strainer an evergreen product or seasonal?

How many units are competitors selling for "cable organizer"?

Are any new sellers succeeding in the kitchen drawer organizer market?

What revenue would a ₹399 product at BSR 3,500 make per month?

Calculate the profit for a ₹399 product that costs ₹120.

Plan a ₹20,000 launch for a ₹399 sink strainer that costs ₹120.

Find suppliers for cable organizers in Chennai or Tamil Nadu.

Find customer complaints about manual soap dispensers.

Generate an Amazon India listing for a reusable silicone food storage bag.

Scrape live Amazon India results for "silicone sink strainer".

Tear down ASIN B0XXXXXXXX and tell me how to beat that listing.

What should I bid on Amazon Ads for a ₹399 product that costs ₹120?

Plan a ₹6,000/month PPC campaign for my sink strainer launch.

Check the scraper status.

Un flujo de trabajo natural: filtrar ideas → comprobar demanda y evergreen → comprobar competidores y vendedores nuevos → calcular beneficio → planificar el lanzamiento → investigar palabras clave → generar el listado.

docs/PROMPTS.md es la biblioteca completa de prompts — 56 prompts de copiar y pegar agrupados por tarea, flujos de trabajo encadenados con varias herramientas y prompts que hacen que Claude muestre qué números son en vivo y cuáles estimados.

Modo de demostración

Con DEMO_MODE=true (el valor predeterminado) todas las herramientas funcionan sin una sola clave de API de pago.

• Los datos de muestra son deterministas: la misma consulta siempre devuelve los mismos números, por lo que los resultados son reproducibles y comprobables.

• Cada valor está etiquetado como "data_type": "Demo", "confidence": "Low", "source": "Local Demo Provider".

• El servidor registra una advertencia al inicio para que nadie olvide en qué modo está.

El modo demo es para aprender el flujo de trabajo y probar la integración. Nunca tomes una decisión de compra basada en números de demostración.

Datos en vivo de fuentes gratuitas (sin claves de API)

Todo lo siguiente es gratuito y no necesita clave de API:

uv sync --extra realtime --extra browser
uv run playwright install chromium     # only for render=true

APP_ENV=production
DEMO_MODE=false
PRODUCT_DATA_PROVIDER=scraper
GOOGLE_TRENDS_ENABLED=true
WEB_SEARCH_PROVIDER=duckduckgo
BROWSER_ENABLED=true
BROWSER_ALLOWED_DOMAINS=amazon.in
BROWSER_MIN_DELAY_SECONDS=8

Amazon presenta desafíos de bots al tráfico automatizado. Este servidor detecta y se detiene en ellos en lugar de eludirlos, por lo que el scraping funciona de forma oportunista. Lee docs/SCRAPING.md antes de activarlo: cubre robots.txt frente a Términos de Servicio, las barreras de seguridad y cómo corregir selectores sin tocar el código.

Integración de API de producción

1. Datos de producto. Implementa una subclase de ProductDataProvider en services/amazon_service.py (search_listings y fetch_reviews), o apunta PRODUCT_DATA_BASE_URL / PRODUCT_DATA_API_KEY a una API de terceros aprobada y adapta el mapeo de payload de HttpProductDataProvider. Luego establece DEMO_MODE=false.

2. Amazon SP-API / PA-API. Regístrate como desarrollador, obtén credenciales y añade un proveedor que firme las solicitudes con AMAZON_API_KEY / AMAZON_API_SECRET. build_provider() ya enruta sp-api y pa-api y actualmente lanza un error claro de «no implementado» en lugar de falsificar datos en silencio.

3. Tarifas. Exporta tu tarjeta de tarifas de Seller Central a JSON que coincida con el modelo FeeSchedule, apunta AMAZON_FEE_CONFIG_PATH a él y establece data_type en Verified.

4. Proveedores. Establece SUPPLIER_API_KEY y SUPPLIER_API_BASE_URL; el estado de verificación se transmite desde el proveedor en lugar de asumirse.

Respeta los términos de servicio de cada proveedor. Hacer scraping directamente de Amazon viola sus términos y no está implementado aquí.

Pruebas

uv run pytest                      # whole suite (193 tests)
uv run pytest -v                   # verbose
uv run pytest tests/test_profit_calculator.py
uv run docs/check_connection.py    # end-to-end MCP connection self-test

La cobertura incluye investigación de productos, bandas y pesos de puntuación de oportunidad, análisis de demanda y estacionalidad, análisis de competencia, las matemáticas completas de beneficio (el punto de equilibrio y el precio recomendado se verifican mediante recálculo), configurabilidad del calendario de tarifas, estimación de ingresos y curva BSR, clasificación de vendedores nuevos y objetivo de volumen, puntuación evergreen, todas las barreras de seguridad del scraping (lista de permitidas, robots, presupuesto de página, detección de desafíos de bots), ayudas de análisis de HTML, manejo de entradas no válidas para cada herramienta y determinismo del modo demo.

La suite es completamente offline: Google Trends en vivo, búsqueda web y obtención de páginas se fuerzan a desactivarse para que los resultados sigan siendo deterministas.

La suite fuerza el modo demo, desactiva el almacenamiento en caché y desactiva la persistencia del historial, por lo que nunca toca tu base de datos de investigación.

Solución de problemas

Los registros van a stderr. Define DEBUG=true o LOG_LEVEL=DEBUG para ver el detalle; en Claude Desktop, usa los archivos de registro de MCP (%APPDATA%\Claude\logs en Windows, ~/Library/Logs/Claude en macOS).

Seguridad

Hay tres riesgos asociados a lo que hace este servidor, y cada uno tiene un control explícito. Los detalles completos están en SECURITY.md; los controles se prueban en tests/test_security.py.

SSRF. El esquema, el puerto y la IP resuelta se verifican antes de cada solicitud, y cada salto de redirección se vuelve a validar — de modo que un host en la lista de permitidos no puede redirigir la descarga hacia loopback, un rango privado o el endpoint de metadatos de la nube. Las solicitudes de Playwright pasan por la misma compuerta.

Credenciales. Un filtro de registro que redacta datos elimina claves de API, tokens de portador y parámetros de consulta con secretos de cada registro, incluido el registro de bibliotecas, como las URL de solicitud de httpx. Ninguna salida de herramienta contiene jamás una clave.

Inyección de prompts. Los listados, las reseñas y los resultados de búsqueda extraídos son texto de terceros que llega al contexto de un LLM. Cada campo se sanitiza (se eliminan caracteres de control, de ancho cero y bidireccionales), se escanea en busca de contenido con forma de instrucción y se devuelve con un bloque content_safety. Las instrucciones MCP del servidor le indican al modelo que lo trate como datos, nunca como instrucciones.

También se aplican: un límite de respuesta de 8 MB, un límite de 5 saltos de redirección, rutas de archivo de configuración validadas, SQL parametrizado y ninguna traza de pila que llegue al cliente MCP.

Notas de seguridad

• Las credenciales provienen únicamente de variables de entorno; .env está en gitignore y nada está codificado de forma fija.

• Las trazas de pila nunca llegan al cliente MCP — los errores se registran en el lado del servidor y se devuelven como cargas útiles estructuradas y seguras para el usuario.

• La base de datos almacena únicamente cargas útiles de investigación, no credenciales.

• Las cifras de tarifas y de mercado son configuración, no código, por lo que pueden corregirse sin cambiar el código.

• Nada en este proyecto extrae datos de Amazon ni elude los términos de ningún proveedor.

Hoja de ruta

• Proveedores reales de SP-API y Product Advertising API con firma de solicitudes

• Seguimiento histórico: tendencias de precio, BSR y valoración a partir de investigaciones almacenadas

• Recursos MCP que exponen el historial de investigación guardado de vuelta a Claude

• Modelado de costes de almacenamiento y publicidad de FBA (punto de equilibrio consciente de ACOS)

• Control por categoría y datos de referencia de certificaciones (BIS / FSSAI)

• Calibración de las curvas de BSR a unidades contra datos reales de ventas de vendedores

• Minería de listas de bestsellers para descubrir productos con demanda demostrada

Contribuciones

Las contribuciones son bienvenidas — consulta CONTRIBUTING.md.

La regla más importante: nunca inventes datos, y nunca dejes que una estimación parezca una medición. La gente gasta dinero real con esta salida, por lo que cada valor lleva su fuente, tipo de datos y nivel de confianza.

Particularmente valioso en este momento:

• Correcciones de selectores cuando Amazon cambia su marcado

• Calibración de las curvas de BSR a unidades contra datos reales de ventas

• Herramientas de GST, cumplimiento de categoría y costes de importación para vendedores indios

• Proveedores reales de SP-API / Product Advertising API

Las solicitudes de extracción que añadan evasión de protección anti-bots (rotación de proxies, suplantación de huellas digitales, resolución de CAPTCHA) serán rechazadas — consulta docs/SCRAPING.md.

Consulta también CODE_OF_CONDUCT.md y SECURITY.md.

Licencia

MIT — libre de usar, modificar y distribuir, incluso con fines comerciales. El software se proporciona tal cual, sin garantía.

Aviso legal

Esta herramienta apoya la investigación; no la sustituye. Las cifras de demanda, ventas y rentabilidad son estimaciones basadas en los datos de entrada y el programa de tarifas configurado — no son garantías. Verifica las tarifas en Seller Central, verifica a cada proveedor personalmente y confirma los requisitos de categoría y marca con Amazon antes de invertir.