MCP CSV Analysis With Gemini AI

使用 Gemini AI 进行 MCP CSV 分析

一款功能强大的 Model Context Protocol（MCP）服务，利用 Google 的 Gemini AI 提供高级 CSV 分析和思维生成能力。此工具可与 Claude Desktop 无缝集成，并提供复杂的数据分析、可视化和自然语言处理功能。

🌟 功能

1. CSV 分析工具（analyze-csv）

• 全面的数据分析：对 CSV 文件进行详细的探索性数据分析（EDA）
• 两种分析模式：
  • basic：快速概览和基本统计数据
  • detailed：深入分析并提供高级洞见
• 分析内容：
  • 对所有列进行统计分析
  • 数据质量评估
  • 模式识别
  • 相关性分析
  • 特征重要性评估
  • 预处理建议
  • 业务洞见
  • 可视化建议

2. 数据可视化工具（visualize-data）

• 交互式可视化：使用 Plotly 创建美观且信息丰富的图表
• 可视化类型：
  • basic：根据数据类型自动选择可视化方式
  • advanced：复杂的多变量可视化
  • custom：用户定义的图表配置
• 图表类型：
  • 用于分布分析的直方图
  • 相关性热力图
  • 散点图
  • 折线图
  • 柱状图
  • 箱线图
• 功能：
  • 自动检测数据类型
  • 智能选择图表
  • 交互式绘图
  • 高分辨率导出
  • 可自定义布局

3. 思维生成工具（generate-thinking）

• 使用 Gemini 的实验性模型生成详细的思维过程文本
• 支持复杂推理和分析
• 保存带时间戳的响应
• 可自定义输出目录

🚀 快速开始

前提条件

• Node.js（v16 或更高版本）
• TypeScript
• Claude Desktop
• Google Gemini API Key
• Plotly 账户（用于可视化）

安装

1. 克隆并设置：

git clone [your-repo-url]
cd mcp-csv-analysis-gemini
npm install

2. 创建 .env 文件：

GEMINI_API_KEY=your_api_key_here

3. 构建项目：

npm run build

Claude Desktop 配置

1. 创建/编辑 %AppData%/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "CSV Analysis": {
      "command": "node",
      "args": ["path/to/mcp-csv-analysis-gemini/dist/index.js"],
      "cwd": "path/to/mcp-csv-analysis-gemini",
      "env": {
        "GEMINI_API_KEY": "your_api_key_here",
        "PLOTLY_USERNAME": "your_plotly_username",
        "PLOTLY_API_KEY": "your_plotly_api_key"
      }
    }
  }
}

2. 重启 Claude Desktop

📊 使用工具

CSV 分析

{
  "name": "analyze-csv",
  "arguments": {
    "csvPath": "./data/your_file.csv",
    "analysisType": "detailed",
    "outputDir": "./custom_output"
  }
}

数据可视化

{
  "name": "visualize-data",
  "arguments": {
    "csvPath": "./data/your_file.csv",
    "visualizationType": "basic",
    "columns": ["column1", "column2"],
    "chartTypes": ["histogram", "scatter"],
    "outputDir": "./custom_output"
  }
}

思维生成

{
  "name": "generate-thinking",
  "arguments": {
    "prompt": "Your complex analysis prompt here",
    "outputDir": "./custom_output"
  }
}

📁 输出结构

output/
├── analysis/
│   ├── csv_analysis_[timestamp]_part1.txt
│   ├── csv_analysis_[timestamp]_part2.txt
│   └── csv_analysis_[timestamp]_summary.txt
├── visualizations/
│   ├── histogram_[column]_[timestamp].png
│   ├── scatter_[columns]_[timestamp].png
│   └── correlation_heatmap_[timestamp].png
└── thinking/
    └── gemini_thinking_[timestamp].txt

📊 可视化类型

基础可视化

• 根据数据类型自动生成
• 包括：
  • 数值列的直方图
  • 相关性热力图
  • 基础散点图

高级可视化

• 更复杂的图表
• 多个变量
• 增强型布局
• 自定义配色方案

自定义可视化

• 用户定义的图表类型
• 可配置参数
• 自定义样式选项
• 高级绘图布局

🛠️ 开发

可用脚本

• npm run build：将 TypeScript 编译为 JavaScript
• npm run start：启动 MCP 服务
• npm run dev：使用 ts-node 在开发模式下运行

环境变量

• GEMINI_API_KEY：你的 Google Gemini API 密钥
• PLOTLY_USERNAME：你的 Plotly 用户名
• PLOTLY_API_KEY：你的 Plotly API 密钥

📝 分析详情

基础分析包括

1. 每列的基本统计摘要
2. 数据质量评估
3. 关键洞见和模式
4. 潜在相关性
5. 进一步分析的建议

详细分析包括

1. 全面的统计分析
   • 分布分析
   • 集中趋势度量
   • 离散程度度量
   • 异常值检测
2. 高级数据质量评估
3. 模式识别
4. 相关性分析
5. 特征重要性分析
6. 预处理建议
7. 可视化建议
8. 业务洞见

⚠️ 限制

• 最大文件大小：取决于系统内存
• 速率限制：取决于 Gemini API 和 Plotly 配额
• 输出令牌限制：每次响应 65,536 个令牌
• CSV 格式：仅支持标准 CSV 文件
• 分析时间：因数据大小和复杂程度而异
• 可视化限制：受 Plotly 免费版限制

🔒 安全注意事项

• 安全存储 API 密钥
• 不要分享你的 .env 文件
• 检查 CSV 数据中是否包含敏感信息
• 对敏感分析使用自定义输出目录
• 妥善保护你的 Plotly 凭据

🐛 故障排除

常见问题

1. API 密钥错误

   • 确认 .env 文件存在
   • 检查 API 密钥是否有效
   • 确保正确加载环境变量

2. CSV 解析错误

   • 确认 CSV 文件格式
   • 检查文件权限
   • 确保文件不为空

3. Claude Desktop 连接问题

   • 确认 config.json 语法正确
   • 检查配置中的文件路径
   • 重启 Claude Desktop

调试模式

在 .env 文件中添加 DEBUG=true 以启用详细日志：

GEMINI_API_KEY=your_key_here
DEBUG=true

📚 API 参考

CSV 分析工具

interface AnalyzeCSVParams {
  csvPath: string;          // Path to CSV file
  outputDir?: string;       // Optional output directory
  analysisType?: 'basic' | 'detailed';  // Analysis type
}

数据可视化工具

interface VisualizeDataParams {
  csvPath: string;          // Path to CSV file
  outputDir?: string;       // Optional output directory
  visualizationType?: 'basic' | 'advanced' | 'custom';  // Visualization type
  columns?: string[];       // Columns to visualize
  chartTypes?: ('scatter' | 'line' | 'bar' | 'histogram' | 'box' | 'heatmap')[];  // Chart types
  customConfig?: Record<string, any>;  // Custom configuration
}

思维生成工具

interface GenerateThinkingParams {
  prompt: string;           // Analysis prompt
  outputDir?: string;       // Optional output directory
}

🤝 贡献

1. Fork 此代码库
2. 创建你的功能分支
3. 提交你的更改
4. 推送到该分支
5. 创建 Pull Request

📄 许可证

MIT 许可证 - 详情请参阅 LICENSE 文件