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

_{↑ Sample dashboard: B08N5WRWNW · 100 reviews · sentiment + pain points + listing improvements, generated by render_dashboard.}

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)

# 1. Get a free Shulex VOC API key (starter credits free)
#    https://apps.voc.ai/openapi
export VOC_API_KEY="your-key"
export ANTHROPIC_API_KEY="sk-ant-..."   # only needed for extract_listing_improvements

# 2. Install
git clone https://github.com/mguozhen/voc-amazon-reviews
cd voc-amazon-reviews
pip install -r mcp_server/requirements.txt

# 3. Register with your agent (one line)
claude mcp add review-analyzer -- python -m mcp_server.server

Now ask any Claude Code / Cursor / Cline session:

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.

bash voc.sh B08N5WRWNW --limit 100 --market US

# 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')"

All 6 tools speak MCP. All return JSON-serializable dicts. Full schemas in mcp_server/README.md.

Most "AI review tools" are a thin LLM wrapper over a brittle scraper. We invert that. The data layer is the moat:

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.

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.

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

• 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-analyzer one-line install
• CLI subprocess engine option (use your Claude subscription, $0 API)
• PyPI publish + official MCP Registry submission
• Smithery / mcp.so / PulseMCP form submissions

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.