MCP CSV Analysis with Gemini AI

Realize análise avançada de CSV e gere insights usando o Google Gemini AI. Requer chaves de API do Gemini e do Plotly.

Documentação

MCP CSV Analysis with Gemini AI

Um poderoso servidor Model Context Protocol (MCP) que fornece análise avançada de CSV e geração de raciocínio usando o Gemini AI do Google. Esta ferramenta integra-se perfeitamente com o Claude Desktop e oferece análise sofisticada de dados, visualização e recursos de processamento de linguagem natural.

🌟 Recursos

1. Ferramenta de Análise de CSV (`analyze-csv`)

Análise Abrangente de Dados: Realiza Análise Exploratória de Dados (EDA) detalhada em arquivos CSV
Dois Modos de Análise:
- basic: Visão geral rápida e estatísticas essenciais
- detailed: Análise aprofundada com insights avançados
Componentes da Análise:
- Análise estatística de todas as colunas
- Avaliação da qualidade dos dados
- Reconhecimento de padrões
- Análise de correlação
- Avaliação da importância das características
- Recomendações de pré-processamento
- Insights de negócios
- Sugestões de visualização

2. Ferramenta de Visualização de Dados (`visualize-data`)

Visualizações Interativas: Cria gráficos bonitos e informativos usando Plotly
Tipos de Visualização:
- basic: Seleção automática de visualização baseada nos tipos de dados
- advanced: Visualizações complexas com múltiplas variáveis
- custom: Configurações de gráficos definidas pelo usuário
Tipos de Gráficos:
- Histogramas para análise de distribuição
- Mapas de calor de correlação
- Gráficos de dispersão
- Gráficos de linha
- Gráficos de barras
- Gráficos de caixa (box plots)
Recursos:
- Detecção automática de tipos de dados
- Seleção inteligente de gráficos
- Gráficos interativos
- Exportações em alta resolução
- Layouts personalizáveis

3. Ferramenta de Geração de Raciocínio (`generate-thinking`)

Gera texto detalhado de processo de raciocínio usando o modelo experimental do Gemini
Suporta raciocínio e análise complexos
Salva respostas com carimbos de data/hora
Diretório de saída personalizável

🚀 Início Rápido

Pré-requisitos

Node.js (v16 ou superior)
TypeScript
Claude Desktop
Chave de API do Google Gemini
Conta Plotly (para visualizações)

Instalação

Clone e configure:

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

Crie o arquivo .env:

GEMINI_API_KEY=your_api_key_here

Compile o projeto:

npm run build

Configuração do Claude Desktop

Crie/Edite %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"
      }
    }
  }
}

Reinicie o Claude Desktop

📊 Usando as Ferramentas

Análise de CSV

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

Visualização de Dados

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

Geração de Raciocínio

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

📁 Estrutura de Saída

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

📊 Tipos de Visualização

Visualizações Básicas

Geradas automaticamente com base nos tipos de dados
Inclui:
- Histogramas para colunas numéricas
- Mapas de calor de correlação
- Gráficos de dispersão básicos

Visualizações Avançadas

Gráficos mais sofisticados
Múltiplas variáveis
Layouts aprimorados
Esquemas de cores personalizados

Visualizações Personalizadas

Tipos de gráficos definidos pelo usuário
Parâmetros configuráveis
Opções de estilo personalizadas
Layouts avançados de gráficos

🛠️ Desenvolvimento

Scripts Disponíveis

npm run build: Compila TypeScript para JavaScript
npm run start: Inicia o servidor MCP
npm run dev: Executa em modo de desenvolvimento com ts-node

Variáveis de Ambiente

GEMINI_API_KEY: Sua chave de API do Google Gemini
PLOTLY_USERNAME: Seu nome de usuário Plotly
PLOTLY_API_KEY: Sua chave de API Plotly

📝 Detalhes da Análise

Análise Básica Inclui

Resumo estatístico básico para cada coluna
Avaliação da qualidade dos dados
Principais insights e padrões
Correlações potenciais
Recomendações para análises adicionais

Análise Detalhada Inclui

Análise estatística abrangente
- Análise de distribuição
- Medidas de tendência central
- Medidas de dispersão
- Detecção de outliers
Avaliação avançada da qualidade dos dados
Reconhecimento de padrões
Análise de correlação
Análise de importância das características
Recomendações de pré-processamento
Sugestões de visualização
Insights de negócios

⚠️ Limitações

Tamanho máximo do arquivo: Depende da memória do sistema
Limites de taxa: Baseados nas cotas da API Gemini e Plotly
Limite de tokens de saída: 65.536 tokens por resposta
Formato CSV: Apenas arquivos CSV padrão
Tempo de análise: Varia com o tamanho e complexidade dos dados
Limites de visualização: Baseados nas restrições do plano gratuito Plotly

🔒 Notas de Segurança

Armazene suas chaves de API com segurança
Não compartilhe seu arquivo .env
Revise os dados CSV quanto a informações sensíveis
Use diretórios de saída personalizados para análises sensíveis
Proteja suas credenciais Plotly

🐛 Solução de Problemas

Problemas Comuns

Erro de Chave de API
- Verifique se o arquivo .env existe
- Verifique a validade da chave de API
- Garanta o carregamento adequado do ambiente
Erro de Análise de CSV
- Verifique o formato do arquivo CSV
- Verifique as permissões do arquivo
- Garanta que o arquivo não esteja vazio
Conexão com o Claude Desktop
- Verifique a sintaxe do config.json
- Verifique os caminhos dos arquivos na configuração
- Reinicie o Claude Desktop

Modo de Depuração

Adicione DEBUG=true ao seu arquivo .env para registro detalhado:

GEMINI_API_KEY=your_key_here
DEBUG=true

📚 Referência da API

Ferramenta de Análise de CSV

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

Ferramenta de Visualização de Dados

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
}

Ferramenta de Geração de Raciocínio

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

🤝 Contribuindo

Faça um fork do repositório
Crie seu branch de funcionalidade
Faça commit das suas alterações
Envie para o branch
Crie um Pull Request

📄 Licença

Licença MIT - Consulte o arquivo LICENSE para detalhes

MCP CSV Analysis with Gemini AI

Documentação