voc-amazon-reviews

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: Amazon All-in-One Scrape 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 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:

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

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:

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

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

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-analyzer one-line install

• CLI 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.