Amazon India Product Research MCP

MCP-сервер (Model Context Protocol), который превращает Claude Desktop в ассистента по исследованию товаров для начинающих продавцов Amazon India. Он оценивает возможности продукта, прогнозирует спрос, оценивает конкуренцию, рассчитывает реальную рентабельность для Amazon India, планирует закупки, анализирует жалобы покупателей, исследует ключевые слова и составляет полный листинг.

Работает через stdio, поэтому подключается напрямую к Claude Desktop.

Впервые здесь? Начните с Руководства по установке и запуску — пошаговая установка, проверка и настройка Claude Desktop, а также раздел по устранению неполадок. О живых данных см. Руководство по живым данным и парсингу.

24 инструмента. Работает без API-ключей — в демо-режиме офлайн или на реальных живых данных из бесплатных источников (Google Trends, DuckDuckGo, публичные страницы amazon.in).

Обзор проекта

Сервер построен вокруг одного профиля продавца:

Каждый инструмент оценивает товары по этим критериям и штрафует за то, что губит новых продавцов: брендовые товары, риск подделок, хрупкие предметы, батарейки, сложную электронику, скоропортящиеся товары, сезонные продукты, одежду с проблемами размеров, тяжёлые товары и категории, где доминируют сильные бренды.

Целостность данных — прежде всего

Этот проект отказывается выдумывать факты о маркетплейсе. Каждый значимый вывод несёт source, data_type, confidence и last_updated, где data_type — одно из Live, Verified, Estimated, Historical или Demo.

• Демо-данные всегда помечаются как Demo и никогда не выдаются за реальные данные Amazon.

• Показатели спроса и ежемесячных продаж — это модельные оценки, а не измеренные продажи Amazon.

• Комиссии Amazon берутся из настраиваемого расписания; прилагаемое помечено как Estimated.

• Поставщики никогда не выдумываются. Без API поставщиков search_suppliers возвращает пустой список поставщиков плюс реальные, публично известные каналы закупок, которые вы можете проверить сами.

• Ни один инструмент никогда не обещает гарантированную прибыль или гарантированные продажи.

Возможности

• 20 MCP-инструментов, покрывающих весь рабочий процесс продавца: поиск, спрос, конкуренция, деньги, листинг, закупки и живые данные

• Бесплатные живые данные без API-ключей: интерес в поиске Google Trends, веб-поиск DuckDuckGo и публичные страницы amazon.in, включая бейджи «купили за последний месяц»

• Оценка выручки и продаж на основе кривых BSR или собственных бейджей покупок Amazon, всегда в виде диапазона с указанием метода

• Определение новых продавцов: у каких конкурентов мало отзывов и кто из них уже продаёт 300+ единиц в месяц — самый сильный сигнал того, что страницу можно выиграть

• Оценка «вечнозелёности» на основе до 5 лет реального поискового интереса, чтобы избежать сезонных неликвидов

• Планирование рекламы Amazon Ads: безубыточный ACOS, лестницы ставок по типу соответствия, назначение ключевых слов, структура кампаний и минус-слова — всё это выводится из вашей собственной юнит-экономики, а не из общих советов

• Взвешенная оценка возможностей от 0 до 100, а также пакетный отбор до 15 идей одновременно

• Расчёт комиссий Amazon India: реферальные, за закрытие, FBA / Easy Ship / Self Ship, GST с комиссий, резерв на возврат, безубыточность и рекомендуемая цена

• Планирование запуска: количество заказов, распределение бюджета, рекламный бюджет, точка повторного заказа, окупаемость

• Кластеризация жалоб на отзывы с конкретными исправлениями на уровне поставщика

• Исследование ключевых слов, черновик листинга и план изображений из семи слотов

• Соблюдающий требования парсинг: robots.txt, белый список, задержка обхода, бюджет страниц и жёсткая остановка при бот-проверках — без обхода защиты от ботов

• История исследований хранится в SQLite или PostgreSQL

• Полный демо-режим: всё работает офлайн, детерминированно

Архитектура

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

Правила, которым следует код: server.py не содержит бизнес-логики, инструменты не содержат бизнес-логики, вся она находится в сервисах.

Установка

Требования: Python 3.11+ и uv. В Руководстве по установке и запуску каждый шаг описан подробно.

Использование без клонирования

uvx amazon-india-seller-mcp

Это вся установка. Укажите Claude Desktop на это:

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

Или установите в окружение

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

Или работайте из исходного кода (для разработки)

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

Для бесплатных живых данных нужны дополнительные зависимости: 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

Виртуальное окружение

uv sync управляет виртуальным окружением за вас; запускайте команды с помощью uv run. Если вы предпочитаете активировать его вручную:

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

Зависимости

Объявлены в pyproject.toml и зафиксированы в uv.lock:

mcp, pydantic, pydantic-settings, httpx, sqlalchemy, python-dotenv; pytest в группе разработки.

Добавьте или измените зависимость с помощью uv add <package> / uv remove <package> — никогда не редактируйте lock-файл вручную.

Конфигурация окружения

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

Секреты хранятся только в .env, который в .gitignore. В исходном коде ничего не захардкожено.

Настройка базы данных

Таблицы создаются автоматически при запуске. Ничего вручную выполнять не нужно.

Разработка (по умолчанию): SQLite в ./amazon_product_mcp.db.

PostgreSQL:

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

Столбцы с JSON-нагрузкой автоматически сопоставляются с JSONB в PostgreSQL и JSON в SQLite. Установите драйвер вместе с ним: uv add psycopg[binary].

Хранимые модели: ProductResearch, DemandAnalysis, CompetitionAnalysis, ProfitCalculation, SupplierResearch — каждая хранит product_name, marketplace, research_data, data_source, data_type, confidence, created_at, updated_at.

Хранение истории выполняется по принципу best-effort: если база данных недоступна, инструменты продолжают работать, а ошибка логируется, а не показывается.

Запуск 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

Процесс общается по протоколу MCP через stdio, поэтому он будет молча ждать клиента — это нормальное поведение. Логи идут в stderr, оставляя stdout чистым для протокольного трафика. Остановите его с помощью Ctrl+C.

Конфигурация Claude Desktop

1. Откройте файл конфигурации Claude Desktop:

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

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

2. Скопируйте блок mcpServers из mcp.json.example в него, заменив пути на свои абсолютные пути:

{
  "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" }
    }
  }
}

В Windows используйте .venv\\Scripts\\python.exe и экранируйте обратную косую черту. Вариант uv --directory ... run server.py также включён в пример файла.

3. Полностью выйдите из Claude Desktop и перезапустите его (закройте из трея/меню — перезагрузка окна недостаточна).

4. Проверьте подключение: инструменты появятся в меню инструментов Claude Desktop, а запрос «Рассчитай прибыль для товара за ₹399, который стоит ₹120» должен вызвать calculate_profitability.

Доступные MCP-инструменты

Поиск

Спрос

Конкуренция

Деньги

Листинг

Реклама

Поставщики

Живые данные

Оценка перспективности

Примеры промптов

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.

И естественный процесс: отбираем идеи → проверяем спрос и долгосрочность → смотрим конкурентов → новых продавцов → считаем прибыль → планируем запуск → собираем ключевые слова → генерируем объявление.

docs/PROMPTS.md — это полная библиотека промптов — 56 промптов в готовом виде, сгруппированных по задачам, многоинструментальные сценарии и запросы, которые заставляют Claude показывать, какие цифры живые, а какие — оценочные.

Демо-режим

При DEMO_MODE=true (по умолчанию) каждый инструмент работает без единого покупательного API-ключа.

• Эти данные — детерминированные — один и тот же запрос всегда возвращает одни и те же метрики, так как все воспроизводимо и проверяемо.

• Каждое значение помечено "data_type": "Demo", "confidence": "Low", "source": "случайный дан Demo Provider".

• The server logs a warning on start-up so everyone knows which mode they started.

Демо-режим нужен, чтобы изучить процесс и протестировать интеграцию. Никогда не принимайте решения о закупке по демо-данным.

Живые данные на бесплатных источниках (без API-ключей)

Всё ниже бесплатно и не требует 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 кидает вызовы-боты автоматическому трафику. Этот сервер детекٹ합니다 и останавливается на них, а не обходит, так что scraping работает настоящие и только тогда, когда выходит. Перед тем как включить, прочитайте docs/SCRAPING.md — там описаны robots.txt против Terms of Service, защитные ограничения и то, как чинить селекторы без кода.

Интеграция продакшен-API

1. Данные по продуктам. Создайте подкласс ProductDataProvider в services/amazon_service.py (search_listings and fetch_reviews) или укажите PRODUCT_DATA_BASE_URL / PRODUCT_DATA_API_KEY для стороннего API, который одобрен, и адаптируйте отображение payload в HttpProductDataProvider. Затем поставьте DEMO_MODE=false.

2. Amazon SP-API / PA-API. Зарегистрируйтесь как разработчик, получите credentials и добавьте провайдера, который подписывает запросы через AMAZON_API_KEY / AMAZON_API_SECRET. build_provider() уже программирует параметры sp-api и pa-api и сейчас бросает конкретную ошибку "not implemented", а не молча подделывает данные.

3. Комиссии. Экспортируйте уровень комиссий Seller Central в JSON по модели FeeSchedule, установите AMAZON_FEE_CONFIG_PATH на него и укажите data_type = Verified.

4. Поставщики. Установите SUPPPLIER_API_KEY и SUPPLIER_API_BASE_URL; статус проверки передается от провайдера, а не присваивается.

Соблюдайте условия каждого поставщика. Прямой пакeting Amazon нарушает их условия и таким образом не реализован.

Тестирование

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

Среди coverage — исследование товаров, bands over-works and accurate for opportunity, demand and seasonality, изучение конкурентов, полный math прибыль (бесзубыточность и рекомендуемую цену проверяют повторным пересчетом), различные конфигурации таблицы комиссий, прогноз продаж и кривой BSR, классификация новых продавцов и объёмов, evergreen-оценка, каждый защитный механизм скрейпленга (allowlist, robots, page budget, detection challenge ботов), helpers для HTML-парсинга, invalid-input для каждого инструмента и детерминизм демо-режима.

Набор полностью офлайн: живые Google Trends, веб-поиск и загрузка страниц форсировано отключены, так что результаты детерминированы.

Сет форсирует демо-режим, отключает кеш и отключается от истории, поэтому не трогает вашу исследовательскую базу.

Устранение неполадок

Логи пишутся в stderr. Установите DEBUG=true или LOG_LEVEL=DEBUG для подробного вывода; в Claude Desktop используйте файлы-логов MCP (%APPDATA%\Claude\logs в Windows, ~/Library/Logs/Claude на macOS).

Безопасность

С этим сервером связаны три риска, и для каждого предусмотрено явное средство контроля. Полные подробности — в SECURITY.md; средства контроля проверены в tests/test_security.py.

SSRF. Перед каждым запросом проверяются схема, порт и разрешённый IP-адрес, а каждый шаг перенаправления перепроверяется — поэтому хост из белого списка не может перенаправить запрос на loopback, в частный диапазон или на эндпоинт метаданных облака. Запросы Playwright проходят через тот же барьер.

Учётные данные. Фильтр логов с редактированием удаляет API-ключи, Bearer-токены и секретные query-параметры из каждой записи лога, включая логирование библиотек — например, URL-адреса запросов httpx. Вывод инструментов никогда не содержит ключей.

Инъекция в промпт. Собранные листинги, отзывы и результаты поиска — это сторонний текст, попадающий в контекст LLM. Каждое поле очищается (удаляются управляющие символы, символы нулевой ширины и двунаправленные символы), проверяется на наличие контента в форме инструкций и возвращается с блоком content_safety. Инструкции MCP-сервера предписывают модели трактовать его как данные, а не как инструкции.

Также применяются: лимит ответа 8 МБ, лимит в 5 перенаправлений, проверка путей конфигурационных файлов, параметризованный SQL и запрет на передачу стек-трейсов в MCP-клиент.

Примечания по безопасности

• Учётные данные берутся только из переменных окружения; .env добавлен в .gitignore, и ничего не захардкожено.

• Стек-трейсы никогда не попадают в MCP-клиент — ошибки логируются на стороне сервера и возвращаются в виде структурированных, безопасных для пользователя объектов.

• База данных хранит только исследовательские payload-объекты, никаких учётных данных.

• Значения комиссий и маркетплейса — это конфигурация, а не код, поэтому их можно исправить без изменения кода.

• В этом проекте ничего не скрапится с Amazon и не обходятся условия ни одного провайдера.

Дорожная карта

• Настоящие провайдеры SP-API и Product Advertising API с подписью запросов

• Историческое отслеживание: динамика цены, BSR и рейтинга на основе сохранённых исследований

• MCP-ресурсы, возвращающие в Claude сохранённую историю исследований

• Моделирование затрат на хранение и рекламу FBA (расчёт безубыточности с учётом ACOS)

• Гейтинг категорий и сертификация (BIS / FSSAI): справочные данные

• Калибровка кривых «BSR → количество единиц» по реальным данным продаж продавцов

• Извлечение данных из списков бестселлеров для поиска товаров с подтверждённым спросом

Участие в разработке

Вкладприветствуется — см. CONTRIBUTING.md.

Самое главное правило: никогда не выдумывайте данные и не позволяйте оценке выглядеть как измерение. Люди тратят реальные деньги на этот результат, поэтому каждая величина сопровождается указанием источника, типа данных и уровня уверенности.

Особенно ценно прямо сейчас:

• Исправление селекторов, когда Amazon меняет свою разметку

• Калибровка кривых «BSR → число единиц» по реальным данным продаж

• Инструменты для индийских продавцов: GST, соблюдение категорийных требований и учёт стоимости импорта

• Настоящие провайдеры SP-API / Product Advertising API

Pull request’ы, добавляющие обход бот-защиты (ротация прокси, подмена отпечатков, решение CAPTCHA), будут отклонены — см. docs/SCRAPING.md.

См. также CODE_OF_CONDUCT.md и SECURITY.md.

Лицензия

MIT — свободно к использованию, изменению и распространению, включая коммерческое использование. Программное обеспечение предоставляется «как есть», без гарантий.

Отказ от ответственности

Этот инструмент помогает проводить исследование, но не заменяет его. Показатели спроса, продаж и прибыльности — это оценки на основе введённых данных и настроенной схемы комиссий, а не гарантии. Проверяйте комиссии в Seller Central, проверяйте каждого поставщика самостоятельно и уточняйте в Amazon требования к категориям и брендам, прежде чем вкладывать средства.