Voc Amazon Reviews

Review Analyzer

eコマースのための、エージェントネイティブな顧客の声。
ASIN または CSV を入力するだけで、センチメント、課題、すぐに使える商品ページの改善案、
そして黒とゴールドを基調とした HTML ダッシュボードを取得できます。MCP ツールは 6 種類。最も安定した Amazon レビューデータレイヤーを基盤としています。

_{↑ ダッシュボードのサンプル：B08N5WRWNW · 100 件のレビュー · センチメント + 課題 + 商品ページの改善案。render_dashboard で生成。}

---

TL;DR

2 種類の入力、6 種類のツール、3 種類の出力です。

   ┌─────────────┐                                            ┌──────────────┐
   │   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 で動作）および スキル（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。

オプション： extract_listing_improvements を有効にするには、"ANTHROPIC_API_KEY": "sk-ant-..." を追加します（Claude を直接呼び出す唯一のツールです。他のツールはキーなしで動作します）。実際の Anthropic キーが必要です。他のプロバイダーのキーは使えません。

初回起動時に依存関係が約 5 秒で解決され、2 回目以降はすぐに起動します。

試してみる

MCP 対応エージェントに次のように依頼します。

B08N5WRWNW の VOC レポートを作成し、ダッシュボードをレンダリングして、~/Desktop/voc.html に保存してください。

エージェントは 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. このリポジトリを GitHub にフォークまたはクローンします。
2. GitHub アカウントを使って smithery.ai にサインインします。
3. Deploy a server を選択し、リポジトリを指定します。Smithery がコンテナをビルドし、HTTPS の MCP エンドポイントを公開します。
4. URL をユーザーに共有します。ユーザーはその 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 にデプロイできるよう vercel.json と app.py も含まれています。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 秒（maxDuration: 60 を設定した Hobby — 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 レポートを作成」— 取得と分析を 1 回の呼び出しで実行
4	extract_listing_improvements	ASIN	★ 差別化要素 — 顧客の言葉に基づく、コピーして使えるタイトル／5 つの箇条書き／説明文
5	analyze_csv	CSV／Excel のパスまたは URL	商品が Amazon にない場合、または独自にスクレイピングしたデータがある場合
6	render_dashboard	VOC レポート	外部依存なしで、単体で使える黒と金を基調とした HTML ダッシュボードを生成

6 つのツールはすべて MCP に対応しています。すべて JSON にシリアライズ可能な dict を返します。完全なスキーマは mcp_server/README.md を参照してください。

---

データレイヤー — これが競争優位性となる理由

多くの「AI レビューツール」は、脆弱なスクレイパーを LLM でラップしただけのものです。私たちは逆のアプローチを取ります。 データレイヤーこそが競争優位性です。

	一般的なセラー向けツールのデータレイヤー	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）に着想を得ています。これらを Shulex VOC OpenAPI のデータレイヤーを備えた、MCP ネイティブなアーキテクチャに適用しました。

アーキテクチャ

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

• 取得＋分析ループ：シェルスクリプト（実績があり、再現可能で、デバッグが容易です）
• リスティングの書き換え：Anthropic SDK を直接使用（claude-opus-4-7＋アダプティブシンキング＋システム評価基準のプロンプトキャッシュ）
• ダッシュボード：標準ライブラリだけで HTML をレンダリング。node も react も不要です

---

配布／掲載先

チャネル	状態
punkpeye/awesome-mcp-servers PR #6528	✅ オープン
cline/mcp-marketplace issue #1602	✅ オープン
Glama	🟢 GitHub トピック経由で自動インデックス登録
mcp.directory	🟢 自動取得
mcp.so / PulseMCP	🟡 保留中（手動でフォームを送信）
Smithery	🟡 コンテナのデプロイ準備完了（リポジトリに smithery.yaml と Dockerfile があります）
Official MCP Registry	🟡 PyPI への公開待ち（W2）

---

ロードマップ

• CSV／Excel を読み込む（あらゆるプラットフォームに対応し、列をあいまい検索で検出）
• 22 次元のタグシステム（YAML で設定可能）
• ブラック＆ゴールドの HTML ダッシュボードツール
• MCP ツールを 6 種類リリース
• npx skills add mguozhen/review-analyzer によるワンラインインストール
• CLI サブプロセスエンジンのオプション（Claude のサブスクリプションを利用し、API 料金を $0 に）
• PyPI への公開＋Official 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 を基盤としています。