MCP CSV Analysis With Gemini AI

Gemini AI による MCP CSV 分析

Google の Gemini AI を使用して、高度な CSV 分析と思考生成機能を提供する強力な Model Context Protocol（MCP）サーバーです。このツールは Claude Desktop とシームレスに連携し、高度なデータ分析、可視化、自然言語処理機能を提供します。

🌟 機能

1. CSV 分析ツール（analyze-csv）

• 包括的なデータ分析：CSV ファイルに対して詳細な探索的データ分析（EDA）を実行します
• 2 つの分析モード：
  • 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 [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. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. 変更をコミットします
4. ブランチにプッシュします
5. Pull Request を作成します

📄 ライセンス

MIT License - 詳細は LICENSE ファイルをご覧ください