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 statisticsdetailed: 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 typesadvanced: Complex multi-variable visualizationscustom: 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
- Clone and setup:
git clone [your-repo-url]
cd mcp-csv-analysis-gemini
npm install
- Create
.envfile:
GEMINI_API_KEY=your_api_key_here
- Build the project:
npm run build
Claude Desktop Configuration
- 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"
}
}
}
}
- 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 JavaScriptnpm run start: Start the MCP servernpm run dev: Run in development mode with ts-node
Environment Variables
GEMINI_API_KEY: Your Google Gemini API keyPLOTLY_USERNAME: Your Plotly usernamePLOTLY_API_KEY: Your Plotly API key
📝 Analysis Details
Basic Analysis Includes
- Basic statistical summary for each column
- Data quality assessment
- Key insights and patterns
- Potential correlations
- Recommendations for further analysis
Detailed Analysis Includes
- Comprehensive statistical analysis
- Distribution analysis
- Central tendency measures
- Dispersion measures
- Outlier detection
- Advanced data quality assessment
- Pattern recognition
- Correlation analysis
- Feature importance analysis
- Preprocessing recommendations
- Visualization suggestions
- 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
.envfile - Review CSV data for sensitive information
- Use custom output directories for sensitive analyses
- Secure your Plotly credentials
🐛 Troubleshooting
Common Issues
-
API Key Error
- Verify
.envfile exists - Check API key validity
- Ensure proper environment loading
- Verify
-
CSV Parsing Error
- Verify CSV file format
- Check file permissions
- Ensure file is not empty
-
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
- Fork the repository
- Create your feature branch
- Commit your changes
- Push to the branch
- Create a Pull Request
📄 License
MIT License - See LICENSE file for details