MCP Data Visualization Server

🎯 MCP Data Visualization Server

Transforme linguagem natural em visualizações de dados bonitas e interativas usando o Claude Desktop com suporte a DuckDB e Databricks – instalação com um único comando!

✨ Recursos

• 🚀 Instalação com Um Comando - pip install mcp-visualization-duckdb
• 🔧 Configuração Automática - Configura automaticamente o Claude Desktop
• 🗣️ Interface em Linguagem Natural - Converse com o Claude para criar visualizações
• 📊 Gráficos Interativos - Widgets HTML com Plotly
• 🏢 Integração com Databricks - Conecte-se a SQL warehouses do Databricks com gerenciamento seguro de credenciais
• 🗃️ Suporte a DuckDB - Banco de dados local com importação de CSV e navegador interativo
• 🔄 Multi-Banco de Dados - Alterne facilmente entre DuckDB e Databricks
• 🧠 Análise Baseada em Regras - Sugestões inteligentes de gráficos sem dependências externas de LLM
• 📈 Vários Tipos de Gráficos - Barras, linhas, dispersão, pizza, histograma, box plots, mapas de calor e gráficos de área
• 🔍 Insights Inteligentes - Análise estatística automática e detecção de padrões
• 🛡️ Segurança em Primeiro Lugar - Proteção contra injeção SQL, armazenamento criptografado de credenciais
• ⚡ Sem Dependências Externas - Funciona totalmente offline com o Claude Desktop

🚀 Instalação Rápida

Opção A: DuckDB (Banco de Dados Local)

# 1. Install the package (includes DuckDB and all dependencies)
pip install mcp-visualization-duckdb

# 2. Configure Claude Desktop automatically
mcp-viz configure

# 3. Restart Claude Desktop and start chatting!

É isso! Nenhuma configuração manual necessária.

Nota: DuckDB e todas as outras dependências são instalados automaticamente com o pacote. Nenhuma instalação separada de banco de dados é necessária!

Opção B: Databricks (Data Warehouse Empresarial)

# 1. Install the package
pip install mcp-visualization-duckdb

# 2. Configure Databricks credentials (secure, interactive setup)
mcp-viz databricks configure

# 3. Configure Claude Desktop (auto-detects Databricks)
mcp-viz configure

# 4. Restart Claude Desktop and start chatting!

Para Databricks, você precisará de:

• Nome do host do workspace Databricks (ex.: your-company.cloud.databricks.com)
• Caminho HTTP do SQL warehouse (ex.: /sql/1.0/warehouses/abc123)
• Token de acesso pessoal (gerado em Configurações do Usuário > Desenvolvedor > Tokens de Acesso)

🔒 Segurança: As credenciais são armazenadas com segurança usando o chaveiro do sistema ou arquivos criptografados. Tokens nunca são armazenados em texto puro ou no histórico de comandos.

O que o instalador faz automaticamente:

• ✅ Detecta sua plataforma (Windows/Mac/Linux)
• ✅ Encontra a configuração do Claude Desktop automaticamente
• ✅ Detecta automaticamente o tipo de banco de dados (DuckDB ou Databricks)
• ✅ Configura o banco de dados com dados de exemplo (DuckDB)
• ✅ Armazena credenciais com segurança (Databricks)
• ✅ Configura os caminhos corretamente
• ✅ Cria backups da configuração existente
• ✅ Valida a configuração para garantir que tudo funcione

🚀 Após a Instalação

Uma vez instalado, você verá instruções detalhadas com:

• Próximos passos para o seu tipo de banco de dados escolhido
• Comandos de início rápido
• Links para bancos de dados de exemplo
• Exemplos de consultas para testar

Execute mcp-viz-setup a qualquer momento para ver novamente o guia pós-instalação!

🔄 Uso Contínuo (Após a Configuração)

✅ Configuração Única Apenas

# Run these commands ONCE:
mcp-viz databricks configure  # First time Databricks setup
mcp-viz configure             # Configure Claude Desktop  
# Restart Claude Desktop

📋 Uso Diário - Sem Necessidade de Reconfiguração

# Just open Claude Desktop and start chatting:
"What Databricks catalogs are available?"
"List tables in the sales catalog" 
"Create a chart of revenue by region"

🔍 Verifique o Status a Qualquer Momento

mcp-viz databricks status    # Shows if credentials exist
mcp-viz databricks test      # Test connection and browse catalogs
mcp-viz status              # Shows MCP server configuration

🔄 Quando Você Precisar Reconfigurar

• ❌ Token expirado (tokens de acesso pessoal podem ter datas de expiração)
• ❌ Trocar de workspace (instância Databricks diferente)
• ❌ Trocar de SQL warehouse (caminho HTTP diferente)
• ❌ Problemas de credencial (execute mcp-viz databricks remove e depois reconfigurar)

💾 Armazenamento Seguro de Credenciais

• 🔒 Criptografadas em disco ou no chaveiro do sistema
• 🔄 Carregadas automaticamente quando o Claude Desktop inicia
• ⚡ Sem necessidade de autenticação repetida

📝 Nota: Após a configuração inicial, você deve conseguir usar o Claude Desktop normalmente sem nenhuma etapa adicional de configuração!

🎮 Uso com o Claude Desktop

Após a instalação, basta conversar com o Claude usando linguagem natural:

Análise de Dados

• "Quais tabelas estão disponíveis?" - Listar tabelas do banco de dados
• "Quais catálogos Databricks estão disponíveis?" - Navegar pelos catálogos Databricks
• "Mostre-me os esquemas no catálogo de vendas" - Listar esquemas
• "Analise a tabela de vendas" - Obter informações da tabela
• "Mostre-me os 10 produtos com maior receita" - Consultar dados

Criando Visualizações

• "Crie um gráfico de barras das vendas por região" - Gerar gráficos
• "Mostre-me a correlação entre preço e quantidade" - Gráficos de dispersão
• "Faça um gráfico de pizza dos segmentos de clientes" - Divisão por categorias
• "Visualize as tendências de vendas ao longo do tempo" - Análise de séries temporais

Gerenciamento de Banco de Dados

DuckDB:

• "Navegue pelos bancos de dados na minha pasta Downloads" - Navegador interativo de bancos de dados
• "Conecte-se a C:/caminho/para/mydata.duckdb" - Trocar de banco de dados
• "Carregue CSV de Downloads/sales.csv como tabela 'sales'" - Importar dados

Databricks:

• "Mude para o catálogo de marketing" - Navegar pelos catálogos
• "Liste os esquemas no catálogo de vendas" - Explorar esquemas
• "A qual banco de dados estou conectado?" - Informações de conexão

🔧 Comandos CLI

O pacote inclui uma CLI poderosa:

# Configuration
mcp-viz configure              # Interactive setup (auto-detects database type)
mcp-viz configure --auto       # Automatic setup with defaults
mcp-viz status                 # Check configuration status

# Management  
mcp-viz test                   # Test server functionality
mcp-viz remove                 # Remove server from Claude Desktop

# DuckDB Database
mcp-viz create-db              # Create sample database
mcp-viz create-db --path ./my-data.duckdb  # Create at specific path

# Databricks Integration
mcp-viz databricks configure   # Setup Databricks credentials (interactive)
mcp-viz databricks status      # Check Databricks connection status
mcp-viz databricks test        # Test connection and browse catalogs
mcp-viz databricks remove      # Remove stored credentials

📊 Tipos de Gráficos Suportados

Tipo de Gráfico	Caso de Uso	Exemplo de Solicitação
Barras	Comparar categorias	"Mostre vendas por região"
Linhas	Mostrar tendências ao longo do tempo	"Trace receitas por mês"
Dispersão	Explorar relações	"Relação entre preço e quantidade"
Pizza	Mostrar proporções	"Divisão por segmento de clientes"
Histograma	Analisar distribuições	"Distribuição dos valores de pedidos"
Box	Comparar distribuições	"Faixas de preço por categoria"
Mapa de calor	Mostrar correlações	"Matriz de correlação das métricas"
Área	Tendências cumulativas	"Vendas cumulativas ao longo do tempo"

🛠️ Solução de Problemas

"Servidor não encontrado" no Claude Desktop

# Check configuration status
mcp-viz status

# Reconfigure if needed
mcp-viz configure --force

# Restart Claude Desktop completely

Erros de "Ferramenta desconhecida"

# Test server functionality
mcp-viz test

# Check if all dependencies are installed
pip install --upgrade mcp-visualization-duckdb

Problemas com Banco de Dados

# Create a fresh database with sample data
mcp-viz create-db

# Check current configuration
mcp-viz status

🔧 Configuração Avançada

Caminho Personalizado do Banco de Dados

O instalador solicitará um local para o banco de dados, ou você pode especificá-lo:

# During configuration
mcp-viz configure
# Database path [/home/user/.mcp-visualization/data.duckdb]: /path/to/my/data.duckdb

Múltiplos Bancos de Dados

Você pode alternar facilmente entre bancos de dados usando o Claude Desktop:

• "Navegue pelos bancos de dados na pasta Documentos"
• "Conecte-se a /caminho/para/outro/bancodedados.duckdb"
• "A qual banco de dados estou conectado atualmente?"

💾 Dados de Exemplo

🎯 Dados de Exemplo Integrados

O pacote cria automaticamente dados de exemplo, incluindo:

• Dados de Vendas - 365 dias de vendas em regiões e produtos
• Dados de Clientes - 1000 registros de clientes com dados demográficos
• Dados de Produtos - 100 produtos com categorias e preços

🌟 Bancos de Dados de Exemplo Adicionais

Quer mais dados para explorar? Confira estes bancos de dados de exemplo de alta qualidade:

Bancos de Dados DuckDB de Exemplo da TimeStored

Os conjuntos de dados disponíveis incluem:

• Dados Financeiros - Preços de ações, dados de negociação, análise de mercado
• NYC Taxi - Registros reais de corridas de táxi em NYC com dados geoespaciais
• Benchmark TPC-H - Dados padrão de teste de desempenho de banco de dados
• E-commerce - Catálogos de produtos, pedidos, comportamento do cliente
• Dados de Sensores IoT - Leituras de sensores e telemetria em séries temporais

Basta baixar qualquer arquivo .duckdb e carregá-lo:

# Download a sample database, then:
"Load database from Downloads/nyc-taxi.duckdb"
"What tables are available in this database?"
"Create a heatmap of taxi pickups by hour and day"

Perfeito para testar, aprender e demonstrar capacidades de visualização de dados!

🏗️ Configuração de Desenvolvimento

Para desenvolvedores que desejam contribuir:

# Clone repository
git clone https://github.com/your-github-username/mcp-visualization-duckdb.git
cd mcp-visualization-duckdb

# Install in development mode
pip install -e .

# Configure for development
mcp-viz configure

# Run tests
python test_package.py

Consulte o Guia de Desenvolvimento para instruções detalhadas.

❓ Perguntas Frequentes

P: Preciso executar mcp-viz databricks configure toda vez?

R: Não! Você só executa uma vez durante a configuração inicial. Depois disso:

• ✅ As credenciais são armazenadas com segurança e carregadas automaticamente
• ✅ Basta abrir o Claude Desktop e começar a conversar
• ✅ Nenhuma autenticação repetida é necessária

P: Como sei se meu Databricks ainda está conectado?

R: Verifique a qualquer momento com:

mcp-viz databricks status    # Shows connection status
mcp-viz databricks test      # Tests connection and shows catalogs

P: Quando preciso reconfigurar?

R: Somente quando:

• Seu token de acesso expira
• Você troca de workspace no Databricks
• Você muda para um SQL warehouse diferente
• As credenciais são corrompidas (raro)

P: Minhas credenciais estão seguras?

R: Sim! As credenciais são:

• 🔒 Criptografadas em disco ou armazenadas no chaveiro do sistema
• 🚫 Nunca armazenadas em texto puro ou no histórico de comandos
• ⚡ Carregadas automaticamente quando necessário

P: Posso usar tanto DuckDB quanto Databricks?

R: Sim! O servidor detecta automaticamente qual tipo de banco de dados usar:

• Configurar Databricks: mcp-viz databricks configure
• Configurar DuckDB: mcp-viz configure
• O servidor usa automaticamente o apropriado

📦 Informações do Pacote

• PyPI: https://pypi.org/project/mcp-visualization-duckdb/
• Repositório: https://github.com/your-github-username/mcp-visualization-duckdb
• Licença: MIT

🤝 Contribuindo

Aceitamos contribuições! O pacote é estruturado para fácil desenvolvimento:

1. Faça um fork do repositório
2. Crie um branch para a funcionalidade
3. Faça suas alterações
4. Execute os testes: python test_package.py
5. Envie um pull request

🙏 Agradecimentos

• Model Context Protocol da Anthropic
• DuckDB para processamento analítico rápido
• Plotly para visualizações interativas
• Claude Desktop pela incrível interface de IA

---

Pronto para transformar sua análise de dados com o Claude Desktop?

pip install mcp-visualization-duckdb && mcp-viz configure

🎉 É isso! Comece a conversar com o Claude sobre seus dados!