🎯 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)

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)

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

📋 Daily Usage - No Reconfiguration Needed

🔍 Check Status Anytime

🔄 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 remove then 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:

📊 Supported Chart Types

🛠️ Troubleshooting

"Server not found" in Claude Desktop

"Unknown tool" errors

Database issues

🔧 Advanced Configuration

Custom Database Path

The installer will prompt you for a database location, or you can specify it:

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:

Perfect for testing, learning, and demonstrating data visualization capabilities!

🏗️ Development Setup

For developers who want to contribute:

See Development Guide for detailed instructions.

❓ Frequently Asked Questions

Q: Do I need to run

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:

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:

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Run tests: python test_package.py

5. 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?

🎉 That's it! Start chatting with Claude about your data!