📊 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分析なし）:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

使い方

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

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構造

日本語:

英語:

サンプルファイル:

• 日本語版: 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分析なし）:

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

設定後、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) による形態素解析

言語判別

自動判別（推奨）:

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

手動指定:

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

英語環境のセットアップ

完全自動セットアップ:

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

• 初回のみ約12MBのモデルダウンロードが発生します（数秒〜数十秒）

• 2回目以降は既存のモデルを使用するため、ダウンロードは不要です

• uvx環境で自動的に uv pip install が実行されます

処理の違い

📖 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"、省略時はコメント列から自動判別）

使用例:

英語CSVの分析例:

🛠️ ローカル開発

環境構築

環境変数設定

ローカルでのテスト

テスト実行

📁 プロジェクト構造

🔄 アップデート方法

最新版を取得するには：

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: 依存関係のエラー

解決策:

📝 ライセンス

MIT License

🤖 Powered by Claude AI