🎯 MCP Data Visualization Server
Transform natural language into beautiful, interactive data visualizations using Claude Desktop with DuckDB and Databricks support - one-command installation!
✨ Features
- 🚀 One-Command Installation -
pip install mcp-visualization-duckdb - 🔧 Automatic Configuration - Automatically sets up Claude Desktop
- 🗣️ Natural Language Interface - Chat with Claude to create visualizations
- 📊 Interactive Charts - Plotly-powered HTML widgets
- 🏢 Databricks Integration - Connect to Databricks SQL warehouses with secure credential management
- 🗃️ DuckDB Support - Local database with CSV import and interactive browser
- 🔄 Multi-Database - Seamlessly switch between DuckDB and Databricks
- 🧠 Rule-Based Analysis - Smart chart suggestions without external LLM dependencies
- 📈 Multiple Chart Types - Bar, line, scatter, pie, histogram, box plots, heatmaps, and area charts
- 🔍 Smart Insights - Automatic statistical analysis and pattern detection
- 🛡️ Security First - SQL injection protection, encrypted credential storage
- ⚡ No External Dependencies - Works entirely offline with Claude Desktop
🚀 Quick Installation
Option A: DuckDB (Local Database)
# 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!
That's it! No manual configuration needed.
Note: DuckDB and all other dependencies are automatically installed with the package. No separate database installation required!
Option B: Databricks (Enterprise Data Warehouse)
# 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!
For Databricks, you'll need:
- Databricks workspace hostname (e.g.,
your-company.cloud.databricks.com) - SQL warehouse HTTP path (e.g.,
/sql/1.0/warehouses/abc123) - Personal access token (generated in Databricks User Settings > Developer > Access Tokens)
🔒 Security: Credentials are stored securely using your system keyring or encrypted files. Tokens are never stored in plain text or command history.
What the installer does automatically:
- ✅ Detects your platform (Windows/Mac/Linux)
- ✅ Finds Claude Desktop config automatically
- ✅ Auto-detects database type (DuckDB or Databricks)
- ✅ Sets up database with sample data (DuckDB)
- ✅ Securely stores credentials (Databricks)
- ✅ Configures paths correctly
- ✅ Creates backups of existing config
- ✅ Validates setup to ensure it works
🚀 After Installation
Once installed, you'll see detailed instructions with:
- Next steps for your chosen database type
- Quick start commands
- Sample database links
- Example queries to try
Run mcp-viz-setup anytime to see the post-installation guide again!
🔄 Ongoing Usage (After Setup)
✅ One-Time Setup Only
# Run these commands ONCE:
mcp-viz databricks configure # First time Databricks setup
mcp-viz configure # Configure Claude Desktop
# Restart Claude Desktop
📋 Daily Usage - No Reconfiguration Needed
# 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"
🔍 Check Status Anytime
mcp-viz databricks status # Shows if credentials exist
mcp-viz databricks test # Test connection and browse catalogs
mcp-viz status # Shows MCP server configuration
🔄 When You Need to Reconfigure
- ❌ Token expires (personal access tokens can have expiration dates)
- ❌ Change workspaces (different Databricks instance)
- ❌ Change SQL warehouses (different HTTP path)
- ❌ Credential issues (run
mcp-viz databricks removethen reconfigure)
💾 Secure Credential Storage
- 🔒 Encrypted on disk or in system keyring
- 🔄 Automatically loaded when Claude Desktop starts
- ⚡ No repeated authentication needed
📝 Note: After initial setup, you should be able to use Claude Desktop normally without any additional configuration steps!
🎮 Usage with Claude Desktop
After installation, simply chat with Claude using natural language:
Data Analysis
- "What tables are available?" - List database tables
- "What Databricks catalogs are available?" - Browse Databricks catalogs
- "Show me schemas in the sales catalog" - List schemas
- "Analyze the sales table" - Get table information
- "Show me the top 10 products by revenue" - Query data
Creating Visualizations
- "Create a bar chart of sales by region" - Generate charts
- "Show me the correlation between price and quantity" - Scatter plots
- "Make a pie chart of customer segments" - Category breakdowns
- "Visualize sales trends over time" - Time series analysis
Database Management
DuckDB:
- "Browse databases in my Downloads folder" - Interactive database browser
- "Connect to C:/path/to/mydata.duckdb" - Switch databases
- "Load CSV from Downloads/sales.csv as table 'sales'" - Import data
Databricks:
- "Switch to the marketing catalog" - Navigate catalogs
- "List schemas in the sales catalog" - Browse schemas
- "What database am I connected to?" - Connection info
🔧 CLI Commands
The package includes a powerful 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
📊 Supported Chart Types
| Chart Type | Use Case | Example Request |
|---|---|---|
| Bar | Compare categories | "Show sales by region" |
| Line | Show trends over time | "Plot revenue over months" |
| Scatter | Explore relationships | "Price vs quantity relationship" |
| Pie | Show proportions | "Customer segment breakdown" |
| Histogram | Analyze distributions | "Distribution of order values" |
| Box | Compare distributions | "Price ranges by category" |
| Heatmap | Show correlations | "Correlation matrix of metrics" |
| Area | Cumulative trends | "Cumulative sales over time" |
🛠️ Troubleshooting
"Server not found" in Claude Desktop
# Check configuration status
mcp-viz status
# Reconfigure if needed
mcp-viz configure --force
# Restart Claude Desktop completely
"Unknown tool" errors
# Test server functionality
mcp-viz test
# Check if all dependencies are installed
pip install --upgrade mcp-visualization-duckdb
Database issues
# Create a fresh database with sample data
mcp-viz create-db
# Check current configuration
mcp-viz status
🔧 Advanced Configuration
Custom Database Path
The installer will prompt you for a database location, or you can specify it:
# During configuration
mcp-viz configure
# Database path [/home/user/.mcp-visualization/data.duckdb]: /path/to/my/data.duckdb
Multiple Databases
You can easily switch between databases using Claude Desktop:
- "Browse databases in Documents folder"
- "Connect to /path/to/another/database.duckdb"
- "What database am I currently connected to?"
💾 Sample Data
🎯 Built-in Sample Data
The package automatically creates sample data including:
- Sales Data - 365 days of sales across regions and products
- Customer Data - 1000 customer records with demographics
- Product Data - 100 products with categories and pricing
🌟 Additional Sample Databases
Want more data to explore? Check out these high-quality sample databases:
TimeStored Sample DuckDB Databases
Available datasets include:
- Financial Data - Stock prices, trading data, market analysis
- NYC Taxi - Real NYC taxi trip records with geospatial data
- TPC-H Benchmark - Standard database performance testing data
- E-commerce - Product catalogs, orders, customer behavior
- IoT Sensor Data - Time-series sensor readings and telemetry
Simply download any .duckdb file and load it:
# 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"
Perfect for testing, learning, and demonstrating data visualization capabilities!
🏗️ Development Setup
For developers who want to contribute:
# 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
See Development Guide for detailed instructions.
❓ Frequently Asked Questions
Q: Do I need to run mcp-viz databricks configure every time?
A: No! You only run it once during initial setup. After that:
- ✅ Credentials are stored securely and auto-loaded
- ✅ Just open Claude Desktop and start chatting
- ✅ No repeated authentication needed
Q: How do I know if my Databricks is still connected?
A: Check anytime with:
mcp-viz databricks status # Shows connection status
mcp-viz databricks test # Tests connection and shows catalogs
Q: When do I need to reconfigure?
A: Only when:
- Your access token expires
- You change Databricks workspaces
- You switch to a different SQL warehouse
- Credentials get corrupted (rare)
Q: Are my credentials safe?
A: Yes! Credentials are:
- 🔒 Encrypted on disk or stored in system keyring
- 🚫 Never stored in plain text or command history
- ⚡ Automatically loaded when needed
Q: Can I use both DuckDB and Databricks?
A: Yes! The server auto-detects which database type to use:
- Configure Databricks:
mcp-viz databricks configure - Configure DuckDB:
mcp-viz configure - Server automatically uses the appropriate one
📦 Package Information
- PyPI: https://pypi.org/project/mcp-visualization-duckdb/
- Repository: https://github.com/your-github-username/mcp-visualization-duckdb
- License: MIT
🤝 Contributing
We welcome contributions! The package is structured for easy development:
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests:
python test_package.py - Submit a pull request
🙏 Acknowledgments
- Model Context Protocol by Anthropic
- DuckDB for fast analytical processing
- Plotly for interactive visualizations
- Claude Desktop for the amazing AI interface
Ready to transform your data analysis with Claude Desktop?
pip install mcp-visualization-duckdb && mcp-viz configure
🎉 That's it! Start chatting with Claude about your data!