survey-insight-mcp

sinjorjob/survey-insight-mcp

3.2

If you are the rightful owner of survey-insight-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Survey Insight MCP Server is an AI-powered tool designed to analyze survey comments and generate interactive dashboards.

📊 Survey Insight MCP Server

AI-powered survey comment analysis MCP server that generates beautiful interactive dashboards.

社内アンケートの自由コメント欄を自動分析し、洗練されたHTMLダッシュボードを生成するMCPサーバです。

📸 生成されるレポート例

エグゼクティブサマリー & WordCloud

キーワードランキング & 分析軸別グラフ

AI課題分析 & 改善提案

✨ 主な機能

  • 📝 CSV自動解析: エンコーディング自動検出、データクレンジング
  • 🔍 形態素解析:
    • 日本語: janomeによる高精度解析
    • 英語: spaCyによる自然言語処理
    • キーワード抽出・頻度分析
  • 🌐 多言語対応:
    • 日本語・英語の自動判別
    • AI分析結果は常に日本語で出力
  • 📈 分析軸対応: 部署、年代、役職などで多角的分析
  • ☁️ WordCloud生成: 美しいカラースキーム（パープルグラデーション）
  • 📊 インタラクティブグラフ: Plotlyで棒グラフ（キーワードランキング）、円グラフ（分析軸別分布）
  • 🤖 AI課題分析: Claude/Gemini APIで課題発見・改善提案
  • 🎨 HTMLダッシュボード: レスポンシブ、アニメーション付き

🚀 クイックスタート

Claude Codeでの使用

方法1: コマンドラインでインストール（推奨）

基本インストール（AI分析なし）:

claude mcp add --transport stdio survey-insight --scope user -- \
  uvx --from git+https://github.com/sinjorjob/survey-insight-mcp.git survey-insight-mcp

AI分析あり - Claude Code Subscription利用（推奨）:

claude mcp add --transport stdio survey-insight --scope user \
  -e USE_CLAUDE_CODE_SUBSCRIPTION=true -- \
  uvx --from git+https://github.com/sinjorjob/survey-insight-mcp.git survey-insight-mcp

AI分析あり - Anthropic Claude API利用:

claude mcp add --transport stdio survey-insight --scope user \
  -e LLM_PROVIDER=anthropic \
  -e LLM_API_KEY=sk-ant-api03-your_key_here \
  -e LLM_MODEL=claude-3-5-sonnet-20241022 -- \
  uvx --from git+https://github.com/sinjorjob/survey-insight-mcp.git survey-insight-mcp

AI分析あり - Google Gemini API利用:

claude mcp add --transport stdio survey-insight --scope user \
  -e LLM_PROVIDER=google \
  -e LLM_API_KEY=your_google_api_key_here \
  -e LLM_MODEL=gemini-2.0-flash-exp -- \
  uvx --from git+https://github.com/sinjorjob/survey-insight-mcp.git survey-insight-mcp

インストール後、Claude Codeを再起動してください。

方法2: 設定ファイルで手動インストール

設定ファイル（Windows: %USERPROFILE%\.claude.json、macOS/Linux: ~/.claude.json）を編集：

基本設定（AI分析なし）:

{
  "mcpServers": {
    "survey-insight": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sinjorjob/survey-insight-mcp.git",
        "survey-insight-mcp"
      ]
    }
  }
}

AI分析あり - Claude Code Subscription利用:

{
  "mcpServers": {
    "survey-insight": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sinjorjob/survey-insight-mcp.git",
        "survey-insight-mcp"
      ],
      "env": {
        "USE_CLAUDE_CODE_SUBSCRIPTION": "true"
      }
    }
  }
}

AI分析あり - Anthropic Claude API利用:

{
  "mcpServers": {
    "survey-insight": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sinjorjob/survey-insight-mcp.git",
        "survey-insight-mcp"
      ],
      "env": {
        "LLM_PROVIDER": "anthropic",
        "LLM_API_KEY": "sk-ant-api03-your_key_here",
        "LLM_MODEL": "claude-3-5-sonnet-20241022"
      }
    }
  }
}

AI分析あり - Google Gemini API利用:

{
  "mcpServers": {
    "survey-insight": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sinjorjob/survey-insight-mcp.git",
        "survey-insight-mcp"
      ],
      "env": {
        "LLM_PROVIDER": "google",
        "LLM_API_KEY": "your_google_api_key_here",
        "LLM_MODEL": "gemini-2.0-flash-exp"
      }
    }
  }
}

設定後、Claude Codeを再起動してください。

LLMプロバイダーの変更方法

後からLLMプロバイダーを変更する場合：

方法A: コマンドで再登録

# 1. 既存の設定を削除
claude mcp remove survey-insight

# 2. 新しいプロバイダーで再登録
# Google Geminiに変更する場合：
claude mcp add --transport stdio survey-insight --scope user \
  -e LLM_PROVIDER=google \
  -e LLM_API_KEY=your_new_key_here \
  -e LLM_MODEL=gemini-2.0-flash-exp -- \
  uvx --from git+https://github.com/sinjorjob/survey-insight-mcp.git survey-insight-mcp

# Anthropic Claudeに変更する場合：
claude mcp add --transport stdio survey-insight --scope user \
  -e LLM_PROVIDER=anthropic \
  -e LLM_API_KEY=sk-ant-api03-your_new_key_here \
  -e LLM_MODEL=claude-3-5-sonnet-20241022 -- \
  uvx --from git+https://github.com/sinjorjob/survey-insight-mcp.git survey-insight-mcp

# 3. Claude Codeを再起動

方法B: 設定ファイルを直接編集 ~/.claude.jsonのenvセクションを編集して、Claude Codeを再起動。

使い方

Claude Code上で以下のように依頼：

examples/sample_survey.csvを分析して、部署別・年代別のレポートを生成してください。

MCPツールが自動的に呼び出され、HTMLレポートとWordCloudが生成されます。

📋 CSVファイル要件

ファイル形式

  • 拡張子: .csv
  • エンコーディング: 自動検出対応
    • cp932 (Excel日本語 / Shift-JIS)
    • shift-jis
    • utf-8-sig (BOM付きUTF-8)
    • utf-8
  • 言語: 日本語・英語に対応
    • 日本語: デフォルトで対応（追加設定不要）
    • 英語: 自動で対応（英語モデルは依存関係に含まれます）
    • コメント列のテキストから言語を自動判別
    • languageパラメータで明示的な指定も可能（"ja" または "en"）
    • AI分析結果は常に日本語で出力（入力言語に関わらず）

データ形式

必須要素:

  • コメント列: 自由記述テキストを含む列
    • 列名に「コメント」「comment」「自由記述」「意見」「感想」「フィードバック」を含む場合は自動検出
    • 上記以外の場合は最も平均文字数が長い文字列型の列を自動選択
    • comment_columnパラメータで明示的に指定も可能

オプション要素:

  • 分析軸列: カテゴリカルデータ（部署、年代、役職など）
    • 以下の条件で自動検出:
      • ユニーク値が2以上
      • ユニーク値が全体の50%未満
      • データ型が文字列 (object) またはカテゴリ (category)
    • analysis_axesパラメータで明示的に指定も可能
    • 除外: コメント列、ID列

データクレンジング:

  • 完全に空の行は自動削除
  • 重複行は自動削除
  • 文字列の前後空白は自動トリミング

サンプルCSV構造

日本語:

部署,年代,コメント
営業,30代,対応が丁寧で良かったです
技術,40代,待ち時間が長いのが気になりました

英語:

Department,Age_Group,Comments_Feedback
Sales,30s,The service was very polite and helpful
Technical,40s,The waiting time was a bit long

サンプルファイル:

  • 日本語版: examples/sample_survey.csv
  • 英語版: examples/healthcare_service_survey_en.csv

📝 AI分析機能について

AI分析なし:

  • 形態素解析、キーワード抽出、グラフ生成、WordCloudのみ実行
  • 環境変数設定不要

AI分析あり:

  • 上記に加えて、AIによる課題発見・改善提案を実行
  • 以下のいずれかの環境変数設定が必要：
    • USE_CLAUDE_CODE_SUBSCRIPTION=true（Claude Codeサブスクリプション）
    • LLM_PROVIDER + LLM_API_KEY（Anthropic/Google API）

🔧 その他のMCPクライアント

Gemini CLI

設定ファイル（Windows: %USERPROFILE%\.gemini\settings.json、macOS/Linux: ~/.gemini/settings.json）を編集：

基本設定（AI分析なし）:

{
  "mcpServers": {
    "survey-insight": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sinjorjob/survey-insight-mcp.git",
        "survey-insight-mcp"
      ]
    }
  }
}

AI分析あり（Google Gemini API利用 - 推奨）:

{
  "mcpServers": {
    "survey-insight": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sinjorjob/survey-insight-mcp.git",
        "survey-insight-mcp"
      ],
      "env": {
        "LLM_PROVIDER": "google",
        "LLM_API_KEY": "your_google_api_key_here",
        "LLM_MODEL": "gemini-2.0-flash-exp"
      }
    }
  }
}

設定後、Gemini CLIを再起動してください。

その他のMCPクライアント

MCP仕様に準拠した任意のクライアントで使用できます：

  • Transport: stdio
  • Command: uvx
  • Args: ["--from", "git+https://github.com/sinjorjob/survey-insight-mcp.git", "survey-insight-mcp"]
  • Environment Variables: 上記の環境変数設定を参照

🌐 多言語対応

Survey Insight MCP Serverは日本語と英語のアンケートに対応しています。

サポート言語

  • 日本語: janome による形態素解析
  • 英語: spacy (en_core_web_sm) による形態素解析

言語判別

自動判別（推奨）:

コメント列のテキストから自動的に言語を判別します。

examples/customer_feedback_en.csvを分析してください。

手動指定:

languageパラメータで明示的に指定することも可能です。

{
  "csv_path": "examples/survey_data.csv",
  "language": "en"  # "ja" or "en"
}

英語環境のセットアップ

完全自動セットアップ:

英語CSVを初めて分析する際、spacyの英語モデル (en_core_web_sm) が完全自動でダウンロードされます。ユーザーによる事前セットアップは一切不要です。

  • 初回のみ約12MBのモデルダウンロードが発生します（数秒〜数十秒）
  • 2回目以降は既存のモデルを使用するため、ダウンロードは不要です
  • uvx環境で自動的に uv pip install が実行されます

処理の違い

処理日本語 (janome)英語 (spacy)
形態素解析✅✅
キーワード抽出表層形を使用レンマ（基本形）を使用
複合名詞抽出✅ 対応❌ 非対応（単語のみ）
品詞フィルタリング名詞・動詞・形容詞NOUN・VERB・ADJ
最小文字数1文字以上3文字以上
ストップワード日本語用リスト英語用リスト

📖 MCPツール仕様

analyze_survey

CSVファイルからアンケート分析を実行し、HTMLレポートとWordCloudを生成します。

パラメータ:

  • csv_path (必須): CSVファイルのパス
  • comment_column (オプション): 自由コメント列の名前（省略時は自動検出）
  • analysis_axes (オプション): 分析軸のリスト（例: ["部署", "年代", "役職"]）
  • output_path (オプション): 出力HTMLパス（デフォルト: output/survey_report.html）
  • enable_ai_analysis (オプション): AI課題分析を有効化（デフォルト: true）
  • language (オプション): 言語コード（"ja" or "en"、省略時はコメント列から自動判別）

使用例:

examples/healthcare_service_survey.csvを分析して、診療科別と年齢層別のレポートを生成してください。

英語CSVの分析例:

examples/customer_feedback_en.csvを分析してください。

🛠️ ローカル開発

環境構築

# リポジトリのクローン
git clone https://github.com/sinjorjob/survey-insight-mcp.git
cd survey-insight-mcp

# uv仮想環境作成
uv venv

# 依存パッケージインストール
uv pip install -e .

環境変数設定

cp .env.example .env
# .envファイルを編集してLLM設定

ローカルでのテスト

# MCPサーバをローカルから実行
uvx --from . survey-insight-mcp

# または、MCP Inspectorでテスト
npm install -g @modelcontextprotocol/inspector
mcp-inspector uvx --from . survey-insight-mcp

テスト実行

# ユニットテスト
pytest

# Lintチェック
ruff check --line-length=127
ruff format --check --diff --line-length=127

📁 プロジェクト構造

survey-insight-mcp/
├── pyproject.toml              # パッケージ設定
├── README.md                   # このファイル
├── LICENSE                     # MITライセンス
├── .env.example                # 環境変数テンプレート
├── src/survey_insight/
│   ├── server.py              # エントリーポイント
│   ├── mcp_server.py          # MCPサーバ実装
│   ├── csv_loader.py          # CSV読み込み
│   ├── text_analyzer.py       # 形態素解析
│   ├── chart_generator.py     # グラフ生成
│   ├── ai_analyzer.py         # AI課題分析
│   └── templates/
│       └── dashboard.html     # HTMLテンプレート
├── tests/                     # テストコード
└── examples/                  # サンプルCSVファイル

🔄 アップデート方法

最新版を取得するには：

# uvxキャッシュをクリア
uv cache clean

# Claude Code / Gemini CLIを再起動

uvxは自動的に最新のコミットを取得します。

🐛 トラブルシューティング

問題1: MCPサーバが表示されない

解決策:

  1. Claude Code設定ファイル（~/.claude.json）を確認
  2. GitHubリポジトリのURLが正しいか確認
  3. Claude Codeを再起動

問題2: AI分析が実行されない

原因: 環境変数が正しく設定されていない

解決策:

  • USE_CLAUDE_CODE_SUBSCRIPTION=true を設定
  • または、LLM_PROVIDER と LLM_API_KEY を設定

問題3: 依存関係のエラー

解決策:

# uvxキャッシュをクリア
uv cache clean --force

# Claude Codeを再起動

📝 ライセンス

MIT License

🤖 Powered by Claude AI