Amazon India 제품 리서치 MCP

Claude Desktop을 초보 Amazon India 셀러를 위한 제품 리서치 어시스턴트로 바꿔주는 MCP(Model Context Protocol) 서버입니다. 제품 기회를 점수화하고, 수요를 추정하며, 경쟁을 평가하고, 실제 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, 반품 준비금, 손익분기, 권장 가격

• 출시 계획: 주문 수량, 예산 분배, 광고 예산, 재주문 시점, 회수 기간

• 리뷰 불만 클러스터링 및 구체적인 공급업체 수준 수정

• 키워드 리서치, 리스팅 초안, 7개 슬롯 이미지 계획

• 규정 준수 우선 스크래핑: 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; dev 그룹에는 pytest.

종속성을 추가하거나 변경하려면 uv add <package> / uv remove <package>를 사용하세요 — lockfile을 수동으로 편집하지 마세요.

환경 구성

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

비밀은 .env에만 저장되며 gitignore됩니다. 소스에 하드코딩된 것은 없습니다.

데이터베이스 설정

테이블은 시작 시 자동으로 생성됩니다. 수동으로 실행할 것이 없습니다.

개발(기본): ./amazon_product_mcp.db의 SQLite.

PostgreSQL:

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

JSON 페이로드 열은 PostgreSQL에서는 JSONB로, SQLite에서는 JSON으로 자동 매핑됩니다. 드라이버를 함께 설치하세요: uv add psycopg[binary].

저장 모델: ProductResearch, DemandAnalysis, CompetitionAnalysis, ProfitCalculation, SupplierResearch — 각각 product_name, marketplace, research_data, data_source, data_type, confidence, created_at, updated_at을 유지합니다.

기록 저장은 최선의 노력 방식입니다: 데이터베이스에 연결할 수 없어도 도구는 계속 작동하며 실패는 표면화되지 않고 로그로 기록됩니다.

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

프로세스는 stdio를 통해 MCP 프로토콜을 사용하므로 클라이언트를 기다리며 조용히 대기합니다 — 이것이 올바른 동작입니다. 로그는 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. mcp.json.example에서 mcpServers 블록을 복사하여 붙여넣고, 경로를 자신의 절대 경로로 바꾸세요:

{
  "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 키 없이 모든 도구가 작동합니다.

• 샘플 데이터는 결정적(deterministic) 입니다 — 동일한 쿼리는 항상 동일한 숫자를 반환하므로 결과를 재현하고 테스트할 수 있습니다.

• 모든 값에는 "data_type": "Demo", "confidence": "Low", "source": "Local Demo Provider" 라벨이 붙습니다.

• 서버는 시작 시 경고를 로그에 기록하여 사용자가 어떤 모드인지 잊지 않도록 합니다.

데모 모드는 워크플로 학습과 통합 테스트를 위한 것입니다. 데모 숫자로 구매 결정을 내리지 마십시오.

무료 소스의 실시간 데이터 (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

아마존은 자동화된 트래픽에 봇 챌린지를 제공합니다. 이 서버는 이를 우회하지 않고 감지하여 중단하므로 스크래핑은 기회적으로 작동합니다. 활성화 전에 docs/SCRAPING.md를 읽으십시오 — robots.txt와 서비스 약관의 차이, 가드레일, 코드 수정 없이 셀렉터를 수정하는 방법을 다룹니다.

프로덕션 API 통합

1. 제품 데이터. services/amazon_service.py에서 ProductDataProvider 하위 클래스를 구현하거나(search_listings 및 fetch_reviews), 승인된 타사 API에 PRODUCT_DATA_BASE_URL / PRODUCT_DATA_API_KEY를 지정하고 HttpProductDataProvider의 페이로드 매핑을 조정합니다. 그런 다음 DEMO_MODE=false로 설정합니다.

2. Amazon SP-API / PA-API. 개발자로 등록하고 자격 증명을 획득한 후 AMAZON_API_KEY / AMAZON_API_SECRET으로 요청에 서명하는 공급자를 추가합니다. build_provider()는 이미 sp-api 및 pa-api를 라우팅하며, 현재는 데이터를 조용히 위조하는 대신 명확한 "구현되지 않음" 오류를 발생시킵니다.

3. 수수료. Seller Central 요금표를 FeeSchedule 모델과 일치하는 JSON으로 내보내고, AMAZON_FEE_CONFIG_PATH를 해당 파일에 지정한 후 data_type을 Verified로 설정합니다.

4. 공급업체. SUPPLIER_API_KEY 및 SUPPLIER_API_BASE_URL을 설정합니다. 검증 상태는 가정이 아닌 공급자로부터 전달됩니다.

각 공급자의 서비스 약관을 준수하십시오. 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

커버리지에는 제품 조사, 기회 점수 밴드 및 가중치, 수요 분석 및 계절성, 경쟁 분석, 전체 수익 계산(손익분기점 및 권장 가격은 재계산으로 검증됨), 수수료 일정 구성 가능성, 매출 및 BSR 곡선 추정, 신규 판매자 및 판매량 목표 분류, 상시 수요 점수, 모든 스크래핑 가드레일(허용 목록, robots, 페이지 예산, 봇 챌린지 감지), HTML 파싱 헬퍼, 모든 도구의 잘못된 입력 처리, 데모 모드 결정성이 포함됩니다.

테스트 스위트는 완전히 오프라인입니다: 실시간 Google Trends, 웹 검색 및 페이지 가져오기는 결과의 결정성을 유지하기 위해 강제로 꺼집니다.

테스트 스위트는 데모 모드를 강제하고, 캐싱을 비활성화하며, 기록 저장을 비활성화하므로 연구 데이터베이스에 영향을 주지 않습니다.

문제 해결

로그는 stderr로 출력됩니다. 자세한 내용은 DEBUG=true 또는 LOG_LEVEL=DEBUG를 설정하세요. Claude Desktop에서는 MCP 로그 파일을 사용하세요(Windows의 경우 %APPDATA%\Claude\logs, macOS의 경우 ~/Library/Logs/Claude).

보안

이 서버가 수행하는 작업에는 세 가지 위험이 따르며, 각각에 명시적인 통제 장치가 있습니다. 자세한 내용은 SECURITY.md에 있으며, 통제 장치는 tests/test_security.py에서 테스트됩니다.

SSRF. 스킴, 포트, 확인된 IP는 모든 요청 전에 검사되며, 모든 리디렉션 홉은 재검증됩니다. 따라서 허용 목록에 있는 호스트가 루프백, 사설 대역 또는 클라우드 메타데이터 엔드포인트로 가져오기를 리디렉션할 수 없습니다. Playwright 요청도 동일한 게이트를 통과합니다.

자격 증명. 편집 로그 필터는 httpx의 요청 URL과 같은 라이브러리 로깅을 포함한 모든 로그 레코드에서 API 키, 베어러 토큰 및 비밀을 포함한 쿼리 매개변수를 제거합니다. 어떤 도구 출력에도 키가 포함되지 않습니다.

프롬프트 인젝션. 스크래핑된 목록, 리뷰 및 검색 결과는 LLM의 컨텍스트에 들어오는 제3자 텍스트입니다. 모든 필드는 정화되고(제어 문자, 제로 너비 문자, 양방향 문자 제거), 명령 형태의 콘텐츠가 있는지 검사되며, content_safety 블록과 함께 반환됩니다. 서버의 MCP 지침은 모델에게 이를 명령이 아닌 데이터로 취급하도록 지시합니다.

또한 8MB 응답 상한, 5홉 리디렉션 제한, 검증된 구성 파일 경로, 매개변수화된 SQL, MCP 클라이언트에 도달하지 않는 스택 추적이 적용됩니다.

보안 참고 사항

• 자격 증명은 환경 변수에서만 가져옵니다. .env는 gitignore 처리되며 하드코딩된 것은 없습니다.

• 스택 추적은 MCP 클라이언트에 도달하지 않습니다. 오류는 서버 측에서 기록되고 구조화된 사용자 안전 페이로드로 반환됩니다.

• 데이터베이스는 연구 페이로드만 저장하며 자격 증명은 저장하지 않습니다.

• 수수료 및 마켓플레이스 수치는 코드가 아닌 구성이므로 코드 변경 없이 수정할 수 있습니다.

• 이 프로젝트는 Amazon을 스크래핑하거나 어떤 제공업체의 약관을 우회하지 않습니다.

로드맵

• 요청 서명이 포함된 실제 SP-API 및 Product Advertising API 제공업체

• 과거 추적: 저장된 연구에서 가격, BSR 및 평점 추세

• 저장된 연구 기록을 Claude에 다시 노출하는 MCP 리소스

• FBA 보관 및 광고 비용 모델링(ACOS 인식 손익분기점)

• 카테고리 수준 게이팅 및 인증(BIS / FSSAI) 참조 데이터

• 실제 판매자 판매 데이터에 대한 BSR-단위 곡선 보정

• 검증된 수요 제품 발견을 위한 베스트셀러 목록 마이닝

기여

기여는 환영합니다 — CONTRIBUTING.md를 참조하세요.

가장 중요한 규칙: 데이터를 절대 조작하지 말고, 추정치가 측정치처럼 보이게 하지 마세요. 사람들은 이 출력에 실제 돈을 지출하므로 모든 값에는 출처, 데이터 유형 및 신뢰도가 포함됩니다.

현재 특히 가치 있는 기여:

• Amazon이 마크업을 변경할 때 셀렉터 수정

• 실제 판매 데이터에 대한 BSR-단위 곡선 보정

• 인도 판매자를 위한 GST, 카테고리 규정 준수 및 수입 비용 도구

• 실제 SP-API / Product Advertising API 제공업체

봇 보호 우회(프록시 순환, 핑거프린트 스푸핑, CAPTCHA 해결)를 추가하는 풀 리퀘스트는 거부됩니다 — docs/SCRAPING.md를 참조하세요.

CODE_OF_CONDUCT.md 및 SECURITY.md도 참조하세요.

라이선스

MIT — 상업적 용도를 포함하여 자유롭게 사용, 수정 및 배포할 수 있습니다. 이 소프트웨어는 보증 없이 있는 그대로 제공됩니다.

고지 사항

이 도구는 연구를 지원하며 연구를 대체하지 않습니다. 수요, 판매 및 수익성 수치는 입력값과 구성된 수수료 일정에 기반한 추정치이며 보장이 아닙니다. 투자 전에 Seller Central에서 수수료를 확인하고, 모든 공급업체를 직접 검증하며, Amazon에서 카테고리 및 브랜드 요구 사항을 확인하세요.