Servidor MCP de Data Visualization

🎯 MCP Data Visualization Server

Transforma el lenguaje natural en visualizaciones de datos hermosas e interactivas usando Claude Desktop con soporte para DuckDB y Databricks - ¡instalación con un solo comando!

✨ Características

🚀 Instalación con un solo comando - pip install mcp-visualization-duckdb
🔧 Configuración automática - Configura Claude Desktop automáticamente
🗣️ Interfaz de lenguaje natural - Chatea con Claude para crear visualizaciones
📊 Gráficos interactivos - Widgets HTML impulsados por Plotly
🏢 Integración con Databricks - Conéctate a almacenes SQL de Databricks con gestión segura de credenciales
🗃️ Soporte DuckDB - Base de datos local con importación CSV y navegador interactivo
🔄 Multi-base de datos - Cambia sin problemas entre DuckDB y Databricks
🧠 Análisis basado en reglas - Sugerencias inteligentes de gráficos sin dependencias externas de LLM
📈 Múltiples tipos de gráficos - Barras, líneas, dispersión, circular, histograma, diagramas de caja, mapas de calor y gráficos de área
🔍 Información inteligente - Análisis estadístico automático y detección de patrones
🛡️ Seguridad primero - Protección contra inyección SQL, almacenamiento cifrado de credenciales
⚡ Sin dependencias externas - Funciona completamente sin conexión con Claude Desktop

🚀 Instalación rápida

Opción A: DuckDB (Base de datos 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!

¡Eso es todo! No se necesita configuración manual.

Nota: DuckDB y todas las demás dependencias se instalan automáticamente con el paquete. ¡No se requiere instalación separada de la base de datos!

Opción B: Databricks (Almacén de datos 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, necesitarás:

Nombre de host del espacio de trabajo de Databricks (ej., your-company.cloud.databricks.com)
Ruta HTTP del almacén SQL (ej., /sql/1.0/warehouses/abc123)
Token de acceso personal (generado en Configuración de usuario de Databricks > Desarrollador > Tokens de acceso)

🔒 Seguridad: Las credenciales se almacenan de forma segura usando el llavero del sistema o archivos cifrados. Los tokens nunca se almacenan en texto plano ni en el historial de comandos.

Lo que el instalador hace automáticamente:

✅ Detecta tu plataforma (Windows/Mac/Linux)
✅ Encuentra la configuración de Claude Desktop automáticamente
✅ Detecta automáticamente el tipo de base de datos (DuckDB o Databricks)
✅ Configura la base de datos con datos de muestra (DuckDB)
✅ Almacena credenciales de forma segura (Databricks)
✅ Configura las rutas correctamente
✅ Crea copias de seguridad de la configuración existente
✅ Valida la configuración para asegurar que funcione

🚀 Después de la instalación

Una vez instalado, verás instrucciones detalladas con:

Próximos pasos para tu tipo de base de datos elegido
Comandos de inicio rápido
Enlaces a bases de datos de muestra
Consultas de ejemplo para probar

¡Ejecuta mcp-viz-setup en cualquier momento para ver la guía posterior a la instalación nuevamente!

🔄 Uso continuo (después de la configuración)

✅ Configuración única solamente

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

📋 Uso diario - Sin necesidad de reconfiguración

# 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"

🔍 Verifica el estado en cualquier 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

🔄 Cuando necesites reconfigurar

❌ El token expira (los tokens de acceso personal pueden tener fechas de expiración)
❌ Cambias de espacio de trabajo (instancia diferente de Databricks)
❌ Cambias de almacén SQL (ruta HTTP diferente)
❌ Problemas de credenciales (ejecuta mcp-viz databricks remove y luego reconfigura)

💾 Almacenamiento seguro de credenciales

🔒 Cifradas en disco o en el llavero del sistema
🔄 Se cargan automáticamente cuando Claude Desktop se inicia
⚡ Sin autenticación repetida necesaria

📝 Nota: Después de la configuración inicial, deberías poder usar Claude Desktop normalmente sin pasos de configuración adicionales.

🎮 Uso con Claude Desktop

Después de la instalación, simplemente chatea con Claude usando lenguaje natural:

Análisis de datos

"¿Qué tablas están disponibles?" - Lista las tablas de la base de datos
"¿Qué catálogos de Databricks están disponibles?" - Explora catálogos de Databricks
"Muéstrame los esquemas en el catálogo de ventas" - Lista esquemas
"Analiza la tabla de ventas" - Obtén información de la tabla
"Muéstrame los 10 productos principales por ingresos" - Consulta datos

Creación de visualizaciones

"Crea un gráfico de barras de ventas por región" - Genera gráficos
"Muéstrame la correlación entre precio y cantidad" - Gráficos de dispersión
"Haz un gráfico circular de segmentos de clientes" - Desgloses por categoría
"Visualiza las tendencias de ventas a lo largo del tiempo" - Análisis de series temporales

Gestión de bases de datos

DuckDB:

"Explora bases de datos en mi carpeta de Descargas" - Navegador interactivo de bases de datos
"Conéctate a C:/ruta/a/misdatos.duckdb" - Cambia de base de datos
"Carga CSV de Descargas/ventas.csv como tabla 'ventas'" - Importa datos

Databricks:

"Cambia al catálogo de marketing" - Navega catálogos
"Lista los esquemas en el catálogo de ventas" - Explora esquemas
"¿A qué base de datos estoy conectado?" - Información de conexión

🔧 Comandos CLI

El paquete incluye una potente CLI:

# 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 compatibles

Tipo de gráfico	Caso de uso	Solicitud de ejemplo
Barras	Comparar categorías	"Muestra ventas por región"
Líneas	Mostrar tendencias a lo largo del tiempo	"Grafica ingresos por meses"
Dispersión	Explorar relaciones	"Relación precio vs cantidad"
Circular	Mostrar proporciones	"Desglose de segmentos de clientes"
Histograma	Analizar distribuciones	"Distribución de valores de pedidos"
Caja	Comparar distribuciones	"Rangos de precios por categoría"
Mapa de calor	Mostrar correlaciones	"Matriz de correlación de métricas"
Área	Tendencias acumulativas	"Ventas acumulativas a lo largo del tiempo"

🛠️ Solución de problemas

"Servidor no encontrado" en Claude Desktop

# Check configuration status
mcp-viz status

# Reconfigure if needed
mcp-viz configure --force

# Restart Claude Desktop completely

Errores de "herramienta desconocida"

# Test server functionality
mcp-viz test

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

Problemas con la base de datos

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

# Check current configuration
mcp-viz status

🔧 Configuración avanzada

Ruta personalizada de base de datos

El instalador te pedirá una ubicación para la base de datos, o puedes especificarla:

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

Múltiples bases de datos

Puedes cambiar fácilmente entre bases de datos usando Claude Desktop:

"Explora bases de datos en la carpeta Documentos"
"Conéctate a /ruta/a/otra/base.duckdb"
"¿A qué base de datos estoy conectado actualmente?"

💾 Datos de muestra

🎯 Datos de muestra integrados

El paquete crea automáticamente datos de muestra que incluyen:

Datos de ventas - 365 días de ventas en regiones y productos
Datos de clientes - 1000 registros de clientes con datos demográficos
Datos de productos - 100 productos con categorías y precios

🌟 Bases de datos de muestra adicionales

¿Quieres más datos para explorar? Consulta estas bases de datos de muestra de alta calidad:

Bases de datos DuckDB de muestra de TimeStored

Los conjuntos de datos disponibles incluyen:

Datos financieros - Precios de acciones, datos de negociación, análisis de mercado
Taxi de NYC - Registros reales de viajes de taxi de NYC con datos geoespaciales
Benchmark TPC-H - Datos estándar de pruebas de rendimiento de bases de datos
Comercio electrónico - Catálogos de productos, pedidos, comportamiento del cliente
Datos de sensores IoT - Lecturas de sensores de series temporales y telemetría

Simplemente descarga cualquier archivo .duckdb y cárgalo:

# 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"

¡Perfecto para probar, aprender y demostrar capacidades de visualización de datos!

🏗️ Configuración de desarrollo

Para desarrolladores que quieran 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

Consulta la Guía de desarrollo para instrucciones detalladas.

❓ Preguntas frecuentes

P: ¿Necesito ejecutar `mcp-viz databricks configure` cada vez?

R: ¡No! Solo lo ejecutas una vez durante la configuración inicial. Después de eso:

✅ Las credenciales se almacenan de forma segura y se cargan automáticamente
✅ Solo abre Claude Desktop y comienza a chatear
✅ No se necesita autenticación repetida

P: ¿Cómo sé si mi Databricks sigue conectado?

R: Verifica en cualquier momento con:

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

P: ¿Cuándo necesito reconfigurar?

R: Solo cuando:

Tu token de acceso expira
Cambias de espacio de trabajo de Databricks
Cambias a un almacén SQL diferente
Las credenciales se corrompen (raro)

P: ¿Mis credenciales están seguras?

R: ¡Sí! Las credenciales están:

🔒 Cifradas en disco o almacenadas en el llavero del sistema
🚫 Nunca se almacenan en texto plano ni en el historial de comandos
⚡ Se cargan automáticamente cuando se necesitan

P: ¿Puedo usar tanto DuckDB como Databricks?

R: ¡Sí! El servidor detecta automáticamente qué tipo de base de datos usar:

Configura Databricks: mcp-viz databricks configure
Configura DuckDB: mcp-viz configure
El servidor usa automáticamente el apropiado

📦 Información del paquete

PyPI: https://pypi.org/project/mcp-visualization-duckdb/
Repositorio: https://github.com/your-github-username/mcp-visualization-duckdb
Licencia: MIT

🤝 Contribuciones

¡Damos la bienvenida a contribuciones! El paquete está estructurado para un desarrollo fácil:

Haz un fork del repositorio
Crea una rama de características
Haz tus cambios
Ejecuta las pruebas: python test_package.py
Envía una solicitud de extracción

🙏 Agradecimientos

Model Context Protocol por Anthropic
DuckDB para procesamiento analítico rápido
Plotly para visualizaciones interactivas
Claude Desktop por la increíble interfaz de IA

¿Listo para transformar tu análisis de datos con Claude Desktop?

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

🎉 ¡Eso es todo! ¡Comienza a chatear con Claude sobre tus datos!

MCP Data Visualization Server

Documentación