使用 Gemini AI 进行 MCP CSV 分析

一个强大的模型上下文协议 (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 密钥
• Plotly 帐户 (用于可视化)

安装

1. 克隆和设置:

git clone [你的仓库 URL]
cd mcp-csv-analysis-gemini
npm install

2. 创建 .env 文件:

GEMINI_API_KEY=你的_api_密钥_在这里

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": "你的_api_密钥_在这里",
        "PLOTLY_USERNAME": "你的_plotly_用户名",
        "PLOTLY_API_KEY": "你的_plotly_api_密钥"
      }
    }
  }
}

2. 重启 Claude Desktop

📊 使用工具

CSV 分析

{
  "name": "analyze-csv",
  "arguments": {
    "csvPath": "./data/你的_文件.csv",
    "analysisType": "detailed",
    "outputDir": "./custom_output"
  }
}

数据可视化

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

思维生成

{
  "name": "generate-thinking",
  "arguments": {
    "prompt": "你复杂的分析提示在这里",
    "outputDir": "./custom_output"
  }
}

📁 输出结构

output/
├── analysis/
│   ├── csv_analysis_[时间戳]_part1.txt
│   ├── csv_analysis_[时间戳]_part2.txt
│   └── csv_analysis_[时间戳]_summary.txt
├── visualizations/
│   ├── histogram_[列]_[时间戳].png
│   ├── scatter_[列]_[时间戳].png
│   └── correlation_heatmap_[时间戳].png
└── thinking/
    └── gemini_thinking_[时间戳].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 语法
   • 检查 config 中的文件路径
   • 重启 Claude Desktop

调试模式

将 DEBUG=true 添加到你的 .env 文件以进行详细日志记录:

GEMINI_API_KEY=你的_密钥_在这里
DEBUG=true

📚 API 参考

CSV 分析工具

interface AnalyzeCSVParams {
  csvPath: string;          // CSV 文件的路径
  outputDir?: string;       // 可选的输出目录
  analysisType?: 'basic' | 'detailed';  // 分析类型
}

数据可视化工具

interface VisualizeDataParams {
  csvPath: string;          // CSV 文件的路径
  outputDir?: string;       // 可选的输出目录
  visualizationType?: 'basic' | 'advanced' | 'custom';  // 可视化类型
  columns?: string[];       // 要可视化的列
  chartTypes?: ('scatter' | 'line' | 'bar' | 'histogram' | 'box' | 'heatmap')[];  // 图表类型
  customConfig?: Record<string, any>;  // 自定义配置
}

思维生成工具

interface GenerateThinkingParams {
  prompt: string;           // 分析提示
  outputDir?: string;       // 可选的输出目录
}

🤝 贡献

1. Fork 仓库
2. 创建你的功能分支
3. 提交你的更改
4. 推送到分支
5. 创建一个 Pull Request

📄 许可证

MIT 许可证 - 有关详细信息，请参见 LICENSE 文件