voc-amazon-reviews

<p align="center"> <img src="docs/logo-400.png" width="120" alt="Review Analyzer"> </p>

<h1 align="center">Review Analyzer</h1>

<p align="center"> <strong>Agent-native voice-of-customer for e-commerce.</strong><br> <em>Drop in an ASIN or a CSV — get sentiment, pain points, copy-ready listing improvements,<br> and a black-gold HTML dashboard. 6 MCP tools. Backed by the most stable Amazon review data layer.</em> </p>

<p align="center"> <a href="#quick-start"><img src="https://img.shields.io/badge/setup-30s-brightgreen?style=flat-square" alt="30s Setup"></a> <a href="#tools"><img src="https://img.shields.io/badge/MCP%20tools-6-FF6A00?style=flat-square" alt="6 MCP tools"></a> <a href="#data-layer"><img src="https://img.shields.io/badge/markets-10-FF9900?style=flat-square&logo=amazon&logoColor=white" alt="10 Markets"></a> <a href="https://github.com/cline/mcp-marketplace/issues/1602"><img src="https://img.shields.io/badge/Cline-submitted-1976d2?style=flat-square" alt="Cline"></a> <a href="https://github.com/punkpeye/awesome-mcp-servers/pull/6528"><img src="https://img.shields.io/badge/awesome--mcp--servers-PR%20%236528-blueviolet?style=flat-square" alt="awesome-mcp-servers"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT"></a> </p>

<p align="center"> <a href="docs/screenshots/dashboard.png"> <img src="docs/screenshots/dashboard.png" alt="Dashboard preview" width="100%"> </a> </p> <p align="center">_{↑ Sample dashboard: B08N5WRWNW · 100 reviews · sentiment + pain points + listing improvements, generated by <code>render_dashboard</code>.}</p>

---

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)

---

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 US

Option 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:

1. Fork or clone this repo to your GitHub.
2. Sign in at smithery.ai with GitHub.
3. Deploy a server → pick the repo. Smithery builds the container and exposes an HTTPS MCP endpoint.
4. 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.server

Option 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
VOC_API_KEY	yes	Shulex VOC OpenAPI key
ANTHROPIC_API_KEY	optional	Only for extract_listing_improvements

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	fetch_reviews	ASIN	You want raw reviews; you'll analyze them yourself
2	analyze_reviews	reviews JSON	You already have reviews and want the VOC report
3	voc_full	ASIN	Default "give me a VOC report" — fetch + analyze in one call
4	extract_listing_improvements	ASIN	★ Differentiator — copy-ready title / 5 bullets / description grounded in customer language
5	analyze_csv	CSV / Excel path or URL	The product is NOT on Amazon, or you have your own scrape
6	render_dashboard	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	✅ extract_listing_improvements (cite-by-pain-point)	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-3

• fetch + 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
punkpeye/awesome-mcp-servers PR #6528	✅ Open
cline/mcp-marketplace issue #1602	✅ Open
Glama	🟢 Auto-indexed via GitHub topics
mcp.directory	🟢 Auto-pull
mcp.so / PulseMCP	🟡 Pending (manual form submit)
Smithery	🟡 Container deploy ready (smithery.yaml + Dockerfile in repo)
Official MCP Registry	🟡 Pending PyPI publish (W2)

---

Roadmap

• [x] Drop in CSV / Excel (any platform, fuzzy column detect)
• [x] 22-dimension tag system (YAML-configurable)
• [x] Black-gold HTML dashboard tool
• [x] 6 MCP tools shipped
• [ ] npx skills add mguozhen/review-analyzer one-line install
• [ ] CLI subprocess engine option (use your Claude subscription, $0 API)
• [ ] PyPI publish + official MCP Registry submission
• [x] Smithery deploy config (smithery.yaml + Dockerfile)
• [x] 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.

<!-- mcp-name: io.github.mguozhen/voc-amazon-reviews-mcp -->