Survey Insight MCP Server

📊 调查洞察MCP服务器

基于人工智能的调查评论分析MCP服务器，可生成美观的交互式仪表板。

自动分析公司内部问卷的自由评论栏精致的HTML仪表板是用于生成（这些）的MCP服务器。

📸 生成的报告示例

执行摘要&词云

关键词排名&分析轴别图表

AI课题分析与改善提案

✨ 主要功能

• 📝 翻译成中文是：📝（这个符号本身没有特定的中文翻译，它通常代表“便签”或“记事本”的意思，但在这里直接保留原样，因为符号本身无需翻译，其含义在上下文中已明确） CSV自动解析自动编码检测、数据清洗
• 🔍 翻译为中文是：放大镜（用于查看细节或搜索） 分词：

- 由janome进行的高精度分析 - 英语：使用spaCy进行自然语言处理 - 关键词提取·频率分析

• 🌐 代表“互联网”或“全球网络”的符号，可直接用其意象表达，无需单独翻译。 多语言支持：

- 日语和英语的自动识别 - AI分析结果始终以日语输出

• 📈 表示“上升趋势”或“增长”。 分析轴对应从部署、年代、职务等多方面进行分析
• ☁️ 云朵 生成词云优美的色彩搭配（紫色渐变）
• 📊（图表） 交互式图表使用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订阅服务（推荐）：

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.jsonmacOS/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订阅服务:

{
  "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报告和词云。

______________________________________________________________________

📋 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.jsonmacOS/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规范的任意客户端配合使用：

• 交通stdio（标准输入输出库）
• 命令: uvx
• 参数/论据: ["--from", "git+https://github.com/sinjorjob/survey-insight-mcp.git", "survey-insight-mcp"]
• 环境变量请参阅上述环境变量设置

______________________________________________________________________

🌐 多语言支持

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的模型（数秒至数十秒）
• 第二次及之后使用的是已有模型，因此无需下载
• 在uvx环境中自动地 uv pip install 将会被执行

处理方式的不同

______________________________________________________________________

📖 MCP工具规格

analyze_survey

从CSV文件执行问卷调查分析，并生成HTML报告和词云。

参数：

• csv_path （必填）：CSV文件路径
• comment_column （可选）：自由评论列的名称（省略时自动检测）
• analysis_axes （可选）：分析轴列表（例如： ["部署", "年代", "役職"]）
• output_path （可选）：输出HTML路径（默认： output/survey_report.html）
• enable_ai_analysis （可选）：启用AI课题分析（默认： true）
• language （可选）：语言代码（"ja" 或者 "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を再起動

______________________________________________________________________

📝 许可证

麻省理工学院许可证

______________________________________________________________________

🤖 由……提供动力/支持 Claude AI（克劳德人工智能）