Voc Amazon Reviews

评论分析器

面向电商的 Agent 原生客户之声分析。
输入 ASIN 或 CSV，即可获取情感分析、痛点、可直接用于商品详情页的改进建议，
以及黑金风格的 HTML 仪表板。6 个 MCP 工具。由最稳定的 Amazon 评论数据层提供支持。

_{↑ 示例仪表板：B08N5WRWNW · 100 条评论 · 情感分析 + 痛点 + 商品详情页改进建议，由 render_dashboard 生成。}

---

简介

两种输入、六个工具、三种输出。

   ┌─────────────┐                                            ┌──────────────┐
   │   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    │
                                                              └──────────────┘

• 输入 — Amazon ASIN（通过 Shulex VOC OpenAPI 自动获取，覆盖 10 个市场）或任意评论 CSV / Excel（Helium 10 / eBay / Shopify / 自定义格式 — 模糊列检测）
• 输出 — Markdown 报告 · 结构化 JSON · 独立 HTML 仪表板
• 使用方式 — MCP 服务（适用于 Claude Code / Cursor / Cline / Continue）和 Skill（适用于 Claude Code）

---

快速开始

选项 A — 作为 MCP 服务（推荐）

需要 uv。

将以下内容添加到 MCP 客户端配置中（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"
      }
    }
  }
}

免费获取 Shulex API 密钥（每月 100 次调用，无需信用卡）：apps.voc.ai/openapi。

可选： 添加 "ANTHROPIC_API_KEY": "sk-ant-..." 以启用 extract_listing_improvements（这是唯一会直接调用 Claude 的工具，其他工具无需此密钥即可使用）。必须使用有效的 Anthropic 密钥；其他提供商的密钥无法使用。

首次运行会在约 5 秒内解析依赖项；之后运行则会立即启动。

试试看

向任何兼容 MCP 的 Agent 提问：

对 B08N5WRWNW 运行 VOC 报告，生成仪表板，并将其保存到 ~/Desktop/voc.html。

Agent 会依次调用 voc_full → render_dashboard，并将文件交给你。

选项 B — 单次运行 CLI

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

选项 C — 使用自己的评论（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')"

选项 D — 部署到 Smithery 托管（无需安装）

远程连接到服务，无需 uvx、Python 或本地安装。请准备 自己的 Shulex API 密钥（首次连接时 Smithery 会提示输入）。

此仓库提供了 Dockerfile 和 smithery.yaml，支持一键部署。 如需运行自己的托管实例：

1. 将此仓库 Fork 或克隆到你的 GitHub。
2. 使用 GitHub 登录 smithery.ai。
3. 部署服务 → 选择此仓库。Smithery 会构建容器并 提供 HTTPS MCP 端点。
4. 将 URL 分享给用户；他们将其粘贴到 Claude / Cursor / Cline 中即可。

同一镜像也可运行在任何支持 Dockerfile 的平台上 — Fly.io、Railway、 Cloudflare Workers（需使用适配器）、Render、Cloud Run。

如需在本地运行 HTTP 传输（例如用于测试）：

MCP_TRANSPORT=streamable-http PORT=8080 python -m mcp_server.server

选项 E — 部署到 Vercel（无服务器）

此仓库还提供了 vercel.json 和 app.py，可一键部署到 Vercel。使用 GitHub 登录 vercel.com，导入仓库，Vercel 会自动检测 Python 函数。

首次部署前，请在 Project Settings → Environment Variables 中设置以下变量：

变量	必需	说明
VOC_API_KEY	是	Shulex VOC OpenAPI 密钥
ANTHROPIC_API_KEY	可选	仅用于 extract_listing_improvements

**超时注意事项：**Vercel 函数的超时上限为 10 秒（Hobby 默认值）、60 秒（Hobby 配置 maxDuration: 60——已在 vercel.json 中设置）或 300 秒（Pro）。voc_full（30–90 秒）和 extract_listing_improvements（20–60 秒）等长时间运行的工具可能会超出这些限制。如需不受限的执行时间，建议选择选项 D（Docker/Render/Fly）或本地安装。

部署后的 MCP 端点：https://your-project.vercel.app/mcp

---

工具

#	工具	输入	适用场景
1	fetch_reviews	ASIN	需要原始评论，打算自行分析
2	analyze_reviews	reviews JSON	已有评论，想获取 VOC 报告
3	voc_full	ASIN	默认的“给我一份 VOC 报告”——一次调用即可抓取并分析
4	extract_listing_improvements	ASIN	★ 差异化优势——根据客户用语生成可直接复制的标题、5 条要点和描述
5	analyze_csv	CSV / Excel 路径或 URL	产品不在 Amazon 上，或你有自己的抓取数据
6	render_dashboard	VOC 报告	生成独立的黑金风格 HTML 仪表盘，无需外部依赖

全部 6 个工具均使用 MCP，且都会返回可序列化为 JSON 的字典。完整架构请参阅 mcp_server/README.md。

---

数据层——这就是我们的护城河

大多数“AI 评论工具”只是基于脆弱爬虫封装的一层大模型。**我们反其道而行之。**数据层才是我们的护城河：

	典型卖家工具的数据层	review-analyzer
来源	网页爬虫 / 未公开文档的抓取 API	付费的 Shulex VOC OpenAPI
可靠性	Amazon 更新 HTML 后就会失效	API 级可靠性，不依赖 DOM
市场	仅限美国或 2–3 个市场	10 个：US、CA、MX、GB、DE、FR、IT、ES、JP、AU
数据量	10–50 条评论（免费版上限）	每个 ASIN 最多 1,000 条评论
新鲜度	每日快照，有时会缓存数天	实时抓取
架构	仅字符串	完整数据：已验证购买、有用票数、vine、变体、日期
非英语市场	经常无法使用 / 未收录	原生采集 + AI 翻译
访问方式	锁定在 UI 中	curl + JSON，完全可脚本化，支持 MCP

对于非 Amazon 平台，analyze_csv 可接受任意评论文件——模糊列匹配会识别 内容 / 评价 / body / review / content，无需重新整理格式。数据来源不限，都能生成相同的 VOC 报告。

---

与其他方案的比较

	review-analyzer	Helium 10 / Data Dive	review-analyzer-skill（Buluu）	通用评论爬虫
输入	ASIN 或 CSV	ASIN（手动操作 UI）	仅 CSV	URL
市场	10 个	1–3 个	取决于用户的数据	1 个
输出	JSON + Markdown + HTML 仪表盘	UI 仪表盘（锁定）	CSV + MD + HTML 仪表盘	原始 CSV
可通过 MCP 调用	✅	❌	❌ 仅限 Claude Code	❌
商品详情文案生成	✅ extract_listing_improvements（按痛点引用依据）	仅关键词研究	❌	❌
成本	Shulex API + Anthropic API（$0.05–0.20/商品详情）	$99–249/月订阅	免费（使用你的 Claude 额度）	免费，但脆弱
开源	✅ MIT	❌	✅ MIT	不一

鸣谢与灵感来源：22 维标签系统、CSV 列模糊检测和黑金风格仪表盘设计均受到 buluslan/review-analyzer-skill（MIT）的启发。我们将这些功能改造为原生支持 MCP 的架构，并采用 Shulex VOC OpenAPI 作为数据层。

---

架构

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

• 抓取 + 分析循环：Shell 脚本（经过验证、可复现、易于调试）
• 重写商品列表：直接使用 Anthropic SDK（claude-opus-4-7 + 自适应思考 + 对系统评估标准启用提示词缓存）
• 仪表板：纯标准库 HTML 渲染，无需 node / react

---

分发渠道 / 在哪里找到我们

渠道	状态
punkpeye/awesome-mcp-servers PR #6528	✅ 已开放
cline/mcp-marketplace issue #1602	✅ 已开放
Glama	🟢 通过 GitHub topics 自动索引
mcp.directory	🟢 自动拉取
mcp.so / PulseMCP	🟡 待处理（需手动提交表单）
Smithery	🟡 已准备好容器部署（仓库中包含 smithery.yaml + Dockerfile）
官方 MCP Registry	🟡 等待发布到 PyPI（W2）

---

路线图

• 导入 CSV / Excel（支持任意平台，模糊列检测）
• 22 维度标签系统（可通过 YAML 配置）
• 黑金风格 HTML 仪表板工具
• 已发布 6 个 MCP 工具
• npx skills add mguozhen/review-analyzer 一行安装
• CLI 子进程引擎选项（使用你的 Claude 订阅，$0 API）
• 发布到 PyPI + 提交至官方 MCP Registry
• Smithery 部署配置（smithery.yaml + Dockerfile）
• Vercel 部署配置（vercel.json + app.py）
• 提交 Smithery / mcp.so / PulseMCP 表单

---

许可证

MIT。参见 LICENSE。

致谢：标签架构、CSV 列检测和仪表板视觉设计的灵感来自 buluslan/review-analyzer-skill。数据层由 Shulex VOC OpenAPI 提供支持。