📊 Survey Insight MCP Server

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

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

📸 生成されるレポート例

<div align="center">

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

<img src="images/report-01.png" width="45%" alt="エグゼクティブサマリー"> <img src="images/report-02.png" width="45%" alt="WordCloud">

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

<img src="images/report-03.png" width="45%" alt="頻出キーワードランキング"> <img src="images/report-04.png" width="45%" alt="分析軸別グラフ">

AI課題分析 & 改善提案

<img src="images/report-05.png" width="45%" alt="AI課題分析"> <img src="images/report-06.png" width="45%" alt="改善提案">

</div>

✨ 主な機能

• 📝 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