# VOC Amazon Reviews [Health: Active] **Category:** ๐Ÿ’ป Developer Tools **Repository:** https://github.com/mguozhen/voc-amazon-reviews **GitHub Stars:** 33 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/voc-amazon-reviews ## Description Amazon review intelligence via Shulex OpenAPI. 10 marketplaces, verified-purchase & Vine signals. ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "voc-amazon-reviews": { "command": "npx", "args": ["-y","skills"] } } ``` ## Documentation & README

Review Analyzer

Review Analyzer

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.

30s Setup 6 MCP tools 10 Markets Cline awesome-mcp-servers MIT

Dashboard preview

โ†‘ Sample dashboard: B08N5WRWNW ยท 100 reviews ยท sentiment + pain points + listing improvements, generated by render_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) --- ## Quick start ### Option A โ€” As an MCP server (recommended) Requires [`uv`](https://docs.astral.sh/uv/getting-started/installation/). Add this to your MCP client config (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code Copilot, Cline, Continue.dev): ```json { "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](https://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 bash voc.sh B08N5WRWNW --limit 100 --market US ``` ### Option C โ€” Bring your own reviews (CSV) ```bash # 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](https://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): ```bash 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](https://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`](https://github.com/mguozhen/voc-amazon-reviews/blob/HEAD/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](https://apps.voc.ai/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](https://github.com/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](https://github.com/punkpeye/awesome-mcp-servers/pull/6528) | โœ… Open | | [cline/mcp-marketplace issue #1602](https://github.com/cline/mcp-marketplace/issues/1602) | โœ… Open | | [Glama](https://glama.ai/mcp/servers) | ๐ŸŸข Auto-indexed via GitHub topics | | [mcp.directory](https://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](https://github.com/mguozhen/voc-amazon-reviews/blob/HEAD/LICENSE). **Acknowledgments**: Tag schema, CSV column detection, and dashboard visual design inspired by [buluslan/review-analyzer-skill](https://github.com/buluslan/review-analyzer-skill). Data layer powered by [Shulex VOC OpenAPI](https://apps.voc.ai/openapi).