MCP CSV Analysis with Gemini AI

A powerful Model Context Protocol (MCP) server that provides advanced CSV analysis and thinking generation capabilities using Google's Gemini AI. This tool integrates seamlessly with Claude Desktop and offers sophisticated data analysis, visualization, and natural language processing features.

🌟 Features

1. CSV Analysis Tool (analyze-csv)

• Comprehensive Data Analysis: Performs detailed Exploratory Data Analysis (EDA) on CSV files
• Two Analysis Modes:
  • basic: Quick overview and essential statistics
  • detailed: In-depth analysis with advanced insights
• Analysis Components:
  • Statistical analysis of all columns
  • Data quality assessment
  • Pattern recognition
  • Correlation analysis
  • Feature importance evaluation
  • Preprocessing recommendations
  • Business insights
  • Visualization suggestions

2. Data Visualization Tool (visualize-data)

• Interactive Visualizations: Creates beautiful and informative charts using Plotly
• Visualization Types:
  • basic: Automatic visualization selection based on data types
  • advanced: Complex multi-variable visualizations
  • custom: User-defined chart configurations
• Chart Types:
  • Histograms for distribution analysis
  • Correlation heatmaps
  • Scatter plots
  • Line charts
  • Bar charts
  • Box plots
• Features:
  • Automatic data type detection
  • Smart chart selection
  • Interactive plots
  • High-resolution exports
  • Customizable layouts

3. Thinking Generation Tool (generate-thinking)

• Generates detailed thinking process text using Gemini's experimental model
• Supports complex reasoning and analysis
• Saves responses with timestamps
• Customizable output directory

🚀 Quick Start

Prerequisites

• Node.js (v16 or higher)
• TypeScript
• Claude Desktop
• Google Gemini API Key
• Plotly Account (for visualizations)

Installation

1. Clone and setup:

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

2. Create .env file:

GEMINI_API_KEY=your_api_key_here

3. Build the project:

npm run build

Claude Desktop Configuration

1. Create/Edit %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. Restart Claude Desktop

📊 Using the Tools

CSV Analysis

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

Data Visualization

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

Thinking Generation

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

📁 Output Structure

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

📊 Visualization Types

Basic Visualizations

• Automatically generated based on data types
• Includes:
  • Histograms for numeric columns
  • Correlation heatmaps
  • Basic scatter plots

Advanced Visualizations

• More sophisticated charts
• Multiple variables
• Enhanced layouts
• Custom color schemes

Custom Visualizations

• User-defined chart types
• Configurable parameters
• Custom styling options
• Advanced plot layouts

🛠️ Development

Available Scripts

• npm run build: Compile TypeScript to JavaScript
• npm run start: Start the MCP server
• npm run dev: Run in development mode with ts-node

Environment Variables

• GEMINI_API_KEY: Your Google Gemini API key
• PLOTLY_USERNAME: Your Plotly username
• PLOTLY_API_KEY: Your Plotly API key

📝 Analysis Details

Basic Analysis Includes

1. Basic statistical summary for each column
2. Data quality assessment
3. Key insights and patterns
4. Potential correlations
5. Recommendations for further analysis

Detailed Analysis Includes

1. Comprehensive statistical analysis
   • Distribution analysis
   • Central tendency measures
   • Dispersion measures
   • Outlier detection
2. Advanced data quality assessment
3. Pattern recognition
4. Correlation analysis
5. Feature importance analysis
6. Preprocessing recommendations
7. Visualization suggestions
8. Business insights

⚠️ Limitations

• Maximum file size: Dependent on system memory
• Rate limits: Based on Gemini API and Plotly quotas
• Output token limit: 65,536 tokens per response
• CSV format: Standard CSV files only
• Analysis time: Varies with data size and complexity
• Visualization limits: Based on Plotly free tier restrictions

🔒 Security Notes

• Store your API keys securely
• Don't share your .env file
• Review CSV data for sensitive information
• Use custom output directories for sensitive analyses
• Secure your Plotly credentials

🐛 Troubleshooting

Common Issues

1. API Key Error

   • Verify .env file exists
   • Check API key validity
   • Ensure proper environment loading

2. CSV Parsing Error

   • Verify CSV file format
   • Check file permissions
   • Ensure file is not empty

3. Claude Desktop Connection

   • Verify config.json syntax
   • Check file paths in config
   • Restart Claude Desktop

Debug Mode

Add DEBUG=true to your .env file for verbose logging:

GEMINI_API_KEY=your_key_here
DEBUG=true

📚 API Reference

CSV Analysis Tool

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

Data Visualization Tool

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
}

Thinking Generation Tool

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

🤝 Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

📄 License

MIT License - See LICENSE file for details