voc-amazon-reviews
This server provides agent-native voice-of-customer (VOC) analysis for e-commerce products, supporting both Amazon ASINs and custom review files. It exposes six MCP-callable tools usable from Claude Code, Cursor, Cline, Continue, and others:
Fetch Amazon Reviews (
fetch_reviews): Retrieve up to 1,000 raw reviews for any ASIN across 10 markets (US, CA, MX, GB, DE, FR, IT, ES, JP, AU) via the Shulex VOC API.Analyze Existing Reviews (
analyze_reviews): Run AI-powered VOC analysis on reviews you already have, producing sentiment breakdowns, pain points, selling points, listing tips, and bilingual summaries — without re-fetching from the API.One-Shot VOC Report (
voc_full): Fetch reviews and run full AI analysis in a single call — the default "give me a VOC report on this ASIN" tool.Generate Listing Improvements (
extract_listing_improvements): Produce copy-ready title, 5 bullet points, description, and missing keywords grounded in actual customer language (requires Anthropic API key).Analyze CSV/Excel Reviews (
analyze_csv): Import review data from non-Amazon sources (Helium 10, eBay, Shopify, AliExpress, etc.) with fuzzy column detection for English and Chinese column names.Render HTML Dashboard (
render_dashboard): Generate a standalone black-gold HTML dashboard featuring sentiment bars, pain-point/selling-point panels, executive summary, and an optional listing optimization card.
All outputs are available as markdown reports, structured JSON, and the interactive HTML dashboard. The server can also be run as a CLI tool or deployed to cloud platforms like Smithery or Vercel.
Fetches and analyzes Amazon product reviews via ASIN across 10 markets (US, CA, MX, GB, DE, FR, IT, ES, JP, AU) using the Shulex VOC OpenAPI data layer, providing sentiment analysis, pain points, and listing improvements.
Accepts eBay review CSV/Excel files for analysis, using fuzzy column detection to handle varying formats and generating the same VOC report and dashboard.
Accepts Helium 10 CSV/Excel exports for analysis, using fuzzy column detection to handle varying formats and generating the same VOC report and dashboard.
Accepts Shopify review CSV/Excel files for analysis, using fuzzy column detection to handle varying formats and generating the same VOC report and dashboard.
TL;DR
Two inputs, six tools, three outputs.
┌─────────────┐ ┌──────────────┐
│ ASIN │──┐ ┌─│ Markdown │
└─────────────┘ │ ┌─────────────────────────┐ │ │ report │
├──────▶ 6 agent-callable tools ├──────┤ ├──────────────┤
┌─────────────┐ │ └─────────────────────────┘ │ │ Structured │
│ CSV / XLSX │──┘ fetch_reviews analyze_csv │ │ JSON │
└─────────────┘ analyze_reviews voc_full │ ├──────────────┤
extract_listing_improvements └─│ Black-gold │
render_dashboard │ HTML deck │
└──────────────┘Inputs — Amazon ASIN (auto-fetched via Shulex VOC OpenAPI, 10 markets) or any review CSV / Excel (Helium 10 / eBay / Shopify / custom — fuzzy column detection)
Outputs — Markdown report · structured JSON · standalone HTML dashboard
Surface — MCP server (works in Claude Code / Cursor / Cline / Continue) and Skill (works in Claude Code)
Related MCP server: LaunchFast MCP
Quick start
Option A — As an MCP server (recommended)
Requires uv.
Add this to your MCP client config (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code Copilot, Cline, Continue.dev):
{
"mcpServers": {
"voc-amazon-reviews": {
"command": "uvx",
"args": ["voc-amazon-reviews-mcp"],
"env": {
"VOC_API_KEY": "your-shulex-key"
}
}
}
}Get a free Shulex API key (100 calls/month, no credit card): apps.voc.ai/openapi.
Optional: Add "ANTHROPIC_API_KEY": "sk-ant-..." to enable extract_listing_improvements (the only tool that calls Claude directly — others work without it). Must be an actual Anthropic key; other providers won't work.
First run resolves dependencies in ~5s; subsequent runs are instant.
Try it
Ask any MCP-compatible agent:
Run a VOC report on
B08N5WRWNW, render the dashboard, and write it to~/Desktop/voc.html.
The agent will call voc_full → render_dashboard and hand you the file.
Option B — One-shot CLI
bash voc.sh B08N5WRWNW --limit 100 --market USOption C — Bring your own reviews (CSV)
# Drop in any reviews CSV (Helium 10 export, eBay scrape, Shopify, custom)
python -c "from mcp_server.tools import analyze_csv, render_dashboard; \
r = analyze_csv('reviews.csv', product_name='My Product'); \
render_dashboard(r, output_path='dashboard.html')"Option D — Hosted on Smithery (no install)
Connect to the server remotely — no uvx, no Python, no local install. Bring
your own Shulex API key (Smithery prompts for it on first connection).
This repo ships a Dockerfile and smithery.yaml for one-click deploy.
To run your own hosted instance:
Fork or clone this repo to your GitHub.
Sign in at smithery.ai with GitHub.
Deploy a server → pick the repo. Smithery builds the container and exposes an HTTPS MCP endpoint.
Share the URL with users; they paste it into Claude / Cursor / Cline.
The same image runs anywhere that takes a Dockerfile — Fly.io, Railway, Cloudflare Workers (with adapter), Render, Cloud Run.
To run the HTTP transport locally (e.g. for testing):
MCP_TRANSPORT=streamable-http PORT=8080 python -m mcp_server.serverOption E — Deploy to Vercel (serverless)
This repo also ships vercel.json + app.py for one-click Vercel
deploys. Sign in at vercel.com with GitHub, import the
repo, and Vercel auto-detects the Python function.
Set these in Project Settings → Environment Variables before the first deploy:
Variable | Required | Notes |
| yes | Shulex VOC OpenAPI key |
| optional | Only for |
Timeout caveat: Vercel functions cap at 10s (Hobby default), 60s
(Hobby with maxDuration: 60 — already set in vercel.json), or 300s
(Pro). Long-running tools like voc_full (30-90s) and
extract_listing_improvements (20-60s) may exceed these limits. For
unbounded execution, prefer Option D (Docker/Render/Fly) or local install.
The MCP endpoint after deploy: https://your-project.vercel.app/mcp
Tools
# | Tool | Input | Use when |
1 |
| ASIN | You want raw reviews; you'll analyze them yourself |
2 |
| reviews JSON | You already have reviews and want the VOC report |
3 |
| ASIN | Default "give me a VOC report" — fetch + analyze in one call |
4 |
| ASIN | ★ Differentiator — copy-ready title / 5 bullets / description grounded in customer language |
5 |
| CSV / Excel path or URL | The product is NOT on Amazon, or you have your own scrape |
6 |
| VOC report | Generate a standalone black-gold HTML dashboard, no external deps |
All 6 tools speak MCP. All return JSON-serializable dicts. Full schemas in mcp_server/README.md.
Data layer — why this is the moat
Most "AI review tools" are a thin LLM wrapper over a brittle scraper. We invert that. The data layer is the moat:
Typical seller-tool data layer | review-analyzer | |
Source | Web scraper / undocumented scrape API | Paid Shulex VOC OpenAPI |
Reliability | Breaks when Amazon updates HTML | API-grade, no DOM dependencies |
Markets | US-only or 2-3 markets | 10: US, CA, MX, GB, DE, FR, IT, ES, JP, AU |
Volume | 10–50 reviews (free-tier cap) | Up to 1,000 reviews per ASIN |
Freshness | Daily snapshots, sometimes cached for days | Live pull |
Schema | Strings only | Full: verified-purchase, helpful votes, vine, variant, dates |
Non-English markets | Often broken / omitted | Native captures + AI translation |
Access | Locked behind a UI | curl + JSON, fully scriptable, MCP-ready |
For non-Amazon platforms, analyze_csv accepts any review file — fuzzy column matching detects 内容 / 评价 / body / review / content so you don't have to reformat. Bring data from anywhere, get the same VOC report.
vs. the alternatives
review-analyzer | Helium 10 / Data Dive | review-analyzer-skill (Buluu) | Generic review scrapers | |
Input | ASIN or CSV | ASIN (manual UI) | CSV only | URL |
Markets | 10 | 1-3 | depends on user's data | 1 |
Output | JSON + Markdown + HTML dashboard | UI dashboard (locked) | CSV + MD + HTML dashboard | Raw CSV |
MCP-callable | ✅ | ❌ | ❌ Claude Code only | ❌ |
Listing copy gen | ✅ | Keyword research only | ❌ | ❌ |
Cost | Shulex API + Anthropic API ($0.05-0.20/listing) | $99-249/month subscription | Free (uses your Claude quota) | Free, brittle |
Open source | ✅ MIT | ❌ | ✅ MIT | varies |
Credit & inspiration: The 22-dimension tag system, fuzzy CSV column detection, and black-gold dashboard aesthetic were inspired by buluslan/review-analyzer-skill (MIT). We adapted them onto an MCP-native architecture with the Shulex VOC OpenAPI data layer.
Architecture
mcp_server/
├── server.py # 6 @mcp.tool decorators
├── tools.py # implementations (subprocess wrappers + Anthropic SDK)
├── csv_loader.py # fuzzy column detection for CSV/Excel input
├── dashboard.py # HTML rendering
├── dashboard_template.html # black-gold template (placeholders)
├── tag_system.yaml # 22-dim tag schema (customizable per category)
├── schemas.py # pydantic structured-output models
└── tests/ # 36 unit tests (subprocess + Anthropic mocked)
fetch.sh / analyze.sh / voc.sh # shell pipeline behind tools 1-3fetch + analyze loop: shell scripts (proven, reproducible, easy to debug)
listing rewrites: Anthropic SDK direct (
claude-opus-4-7+ adaptive thinking + prompt caching on the system rubric)dashboard: pure stdlib HTML rendering, no node / no react
Distribution / where to find us
Channel | Status |
✅ Open | |
✅ Open | |
🟢 Auto-indexed via GitHub topics | |
🟢 Auto-pull | |
mcp.so / PulseMCP | 🟡 Pending (manual form submit) |
Smithery | 🟡 Container deploy ready ( |
Official MCP Registry | 🟡 Pending PyPI publish (W2) |
Roadmap
Drop in CSV / Excel (any platform, fuzzy column detect)
22-dimension tag system (YAML-configurable)
Black-gold HTML dashboard tool
6 MCP tools shipped
npx skills add mguozhen/review-analyzerone-line installCLI subprocess engine option (use your Claude subscription, $0 API)
PyPI publish + official MCP Registry submission
Smithery deploy config (
smithery.yaml+Dockerfile)Vercel deploy config (
vercel.json+app.py)Smithery / mcp.so / PulseMCP form submissions
License
MIT. See LICENSE.
Acknowledgments: Tag schema, CSV column detection, and dashboard visual design inspired by buluslan/review-analyzer-skill. Data layer powered by Shulex VOC OpenAPI.
Available Tools
6 toolsanalyze_csvA
Analyze any review CSV / Excel — not just Amazon.
Drag in a Helium 10 export, an eBay / AliExpress scrape, or your own
Shopify export. The loader fuzzy-matches column names (内容 / 评价 /
body / review / content all detected automatically) so you don't
have to reformat the file.
Use this when:
The product is NOT on Amazon (eBay / AliExpress / D2C)
You already have a reviews file from another source
You want to bypass the Shulex VOC API entirely
Args: csv_path: Local path or HTTP(S) URL to a .csv / .xls / .xlsx file. product_name: Optional friendly name for the report header. market: Optional marketplace tag (US / GB / OTHER, etc.).
Returns: Same shape as analyze_reviews, with meta.columns_detected
showing which columns the loader matched.
Inputs: csv_path (required), product_name, market.
analyze_reviewsA
Run AI analysis on reviews you already have.
Useful when you fetched reviews via fetch_reviews (or your own scraper)
and want the VOC report — sentiment breakdown, pain points, selling
points, listing tips — without re-paying the Shulex API.
Args:
reviews_json: Either fetch.sh's {reviews, meta} envelope, or a
bare list of review objects.
asin: 10-character ASIN that the reviews belong to (for the report
header).
Returns: {asin, market, report_markdown, sentiment, pain_points, selling_points, tips, summary_zh, summary_en}
Inputs: reviews_json (required), asin (required).
extract_listing_improvementsB
Differentiator tool — derive specific, copyable listing improvements from the VOC report, grounded in actual customer language.
Instead of raw search-volume tables (Data Dive style), Claude reads the full VOC report and produces a title, 5 bullets, a description paragraph, and missing keywords — each suggestion citing the pain point it preempts or selling point it amplifies.
Requires ANTHROPIC_API_KEY. Costs ~$0.05-0.20 per call (claude-opus-4-7).
Inputs: asin (required), market, limit.
fetch_reviewsA
Fetch raw Amazon reviews for an ASIN via the Shulex VOC API.
No analysis — returns the raw review array plus metadata. Use this when
you want to plug reviews into your own analysis pipeline, or when you
plan to call analyze_reviews later (avoids paying the Shulex API
twice).
Args: asin: 10-character Amazon product ID (e.g. "B08N5WRWNW"). market: Market code (US, GB, DE, FR, IT, ES, JP, AU, CA, MX) or amazon.* domain ("amazon.co.uk"). Default: US. limit: Number of reviews to fetch (1-1000). Default: 100.
Returns: { "reviews": [{rating, title, body, date, verified, ...}, ...], "meta": {asin, market, total_available, fetched} }
Inputs: asin (required), market, limit.
render_dashboardA
Render a VOC report as a standalone black-gold HTML dashboard.
The output is single-file HTML — no external dependencies, opens directly
in any browser. Includes sentiment bar, pain-point / selling-point
panels, executive summary, and (if improvements provided) a
copy-ready listing optimization card.
Args:
report: Output from analyze_reviews / voc_full / analyze_csv.
improvements: Optional output from extract_listing_improvements.
product_name: Friendly product name for the headline.
output_path: Optional file path to write the HTML to.
Returns: {html, bytes, output_path}
Inputs: report (required), improvements, product_name, output_path.
voc_fullA
One-shot: fetch reviews AND run AI analysis.
The default tool for "give me a VOC report on this ASIN" style requests.
Internally equivalent to bash voc.sh ASIN — calls fetch.sh and
analyze.sh in sequence.
Args: asin: 10-character ASIN. market: Market code or amazon.* domain (default: US). limit: Number of reviews to fetch (default 100, max 1000).
Returns: Same shape as analyze_reviews.
Inputs: asin (required), market, limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Most tools have distinct purposes, but `analyze_reviews` and `voc_full` can be confused since both produce a VOC report, differing only in fetching. `analyze_csv` overlaps conceptually with `analyze_reviews` but is differentiated by input type. Descriptions help clarify but some ambiguity remains.
Names mostly follow verb_noun pattern (analyze_csv, fetch_reviews, render_dashboard) but `extract_listing_improvements` is longer and `voc_full` breaks the pattern entirely. Inconsistent but still readable.
6 tools is well-scoped for the domain of Amazon review analysis. Each tool covers a distinct step (fetch, analyze, improve, render, external CSV analysis) without being too many or too few.
Core workflow (fetch, analyze, improve, visualize) is complete. Minor gaps: no tool for comparing multiple ASINs or batch processing, but this is acceptable for a focused toolkit.
Maintenance
Related MCP Connectors
Amazon competitor research for Claude, ChatGPT and other MCP clients: complaint topics from Amazon's "Customers say" summary of all reviews, 90-day price/rank/review history, listing audits (0-100), keyword rankings with who's advertising, and daily Competitor Watch emails when a rival's price, stock, rank or complaints change. 12 Amazon marketplaces, plus Shopify store teardowns and tracking. 25 free credits. Sample: zonrival.com/sample
AMZScout Skill + MCP gives AI agents live access to real Amazon marketplace data across 14 Amazon marketplaces. Analyze any ASIN, validate product ideas, research niches, compare competitors, discover profitable keywords, and build data-driven PPC strategies using trusted Amazon insights instead of AI assumptions. Works with Claude, ChatGPT, Cursor, and any other MCP-compatible AI client. To connect, you'll need an AMZScout API plan and authorize your account. Get access and view pricing here: https://learn.amzscout.net/amazon-product-api-for-ai-agents
Amazon brand, seller, niche & buy-box intelligence inside your own Claude or ChatGPT.
Amazon Seller Central, Ads and Vendor Central in ChatGPT & Claude. 106 tools; writes need approval.
Related MCP Servers
- AlicenseAqualityBmaintenanceReal-time Amazon Sponsored Products (SP) ad placements, keyword tracking, and comprehensive review data for AI Agents. Enables LLMs to autonomously conduct competitor ad audits, consumer sentiment analysis (VOC), and product optimization.196MIT
- AlicenseNot gradedqualityDmaintenanceEnterprise-grade Amazon & Alibaba intelligence for Claude AI, enabling natural language market research, keyword analysis, and supplier discovery.6 npm2MIT
- AlicenseAqualityCmaintenanceHosted Amazon market-intelligence MCP for Claude and ChatGPT: query brands, sellers, ASINs, under-competed niches, the cross-seller operator network, observed buy-box history, and Amazon/Walmart cross-marketplace overlap. 65 read-only research tools over a pre-collected research dataset.72MIT
- AlicenseNot gradedqualityBmaintenanceAMZScout Skill + MCP gives AI agents live access to real Amazon marketplace data across 14 Amazon marketplaces. Analyze any ASIN, validate product ideas, research niches, compare competitors, discover profitable keywords, and build data-driven PPC strategies using trusted Amazon insights instead of AI assumptions. Works with Claude, ChatGPT, Cursor, and any other MCP-compatible AI client.1MIT