Mcp Data Visualization Server

🎯 MCP 数据可视化服务

借助 Claude Desktop，将自然语言转换为精美的交互式数据可视化，支持 DuckDB 和 Databricks——一条命令即可安装！

✨ 功能特性

• 🚀 一键安装 - pip install mcp-visualization-duckdb
• 🔧 自动配置 - 自动设置 Claude Desktop
• 🗣️ 自然语言界面 - 与 Claude 对话即可创建可视化图表
• 📊 交互式图表 - 由 Plotly 驱动的 HTML 小组件
• 🏢 Databricks 集成 - 连接 Databricks SQL 仓库，并安全管理凭据
• 🗃️ DuckDB 支持 - 本地数据库，支持导入 CSV 和交互式浏览器
• 🔄 多数据库支持 - 在 DuckDB 和 Databricks 之间无缝切换
• 🧠 基于规则的分析 - 无需依赖外部大模型，即可智能推荐图表
• 📈 多种图表类型 - 柱状图、折线图、散点图、饼图、直方图、箱线图、热力图和面积图
• 🔍 智能洞察 - 自动进行统计分析并检测模式
• 🛡️ 安全至上 - 防范 SQL 注入，加密存储凭据
• ⚡ 无需外部依赖 - 与 Claude Desktop 配合，完全离线运行

🚀 快速安装

选项 A：DuckDB（本地数据库）

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

就这么简单！无需手动配置。

注意：安装此软件包时会自动安装 DuckDB 和所有其他依赖项。无需单独安装数据库！

选项 B：Databricks（企业数据仓库）

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

使用 Databricks 需要准备：

• Databricks 工作区主机名（例如，your-company.cloud.databricks.com）
• SQL 仓库 HTTP 路径（例如，/sql/1.0/warehouses/abc123）
• 个人访问令牌（在 Databricks「用户设置」>「开发者」>「访问令牌」中生成）

🔒 安全性：凭据会使用系统密钥环或加密文件安全存储。令牌绝不会以纯文本形式存储，也不会出现在命令历史记录中。

安装程序会自动执行以下操作：

• ✅ 检测你的平台（Windows/Mac/Linux）
• ✅ 自动查找 Claude Desktop 配置
• ✅ 自动检测数据库类型（DuckDB 或 Databricks）
• ✅ 设置数据库并添加示例数据（DuckDB）
• ✅ 安全存储凭据（Databricks）
• ✅ 正确配置路径
• ✅ 备份现有配置
• ✅ 验证设置以确保正常运行

🚀 安装后

安装完成后，你将看到详细说明，包括：

• 所选数据库类型的后续步骤
• 快速入门命令
• 示例数据库链接
• 可尝试的示例查询

随时运行 mcp-viz-setup，再次查看安装后的指南！

🔄 日常使用（设置完成后）

✅ 只需设置一次

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

📋 日常使用——无需重新配置

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

🔍 随时检查状态

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

🔄 需要重新配置的情况

• ❌ 令牌过期（个人访问令牌可能设有过期日期）
• ❌ 更换工作区（使用不同的 Databricks 实例）
• ❌ 更换 SQL 仓库（使用不同的 HTTP 路径）
• ❌ 凭据问题（运行 mcp-viz databricks remove，然后重新配置）

💾 安全存储凭据

• 🔒 加密存储在磁盘上或系统密钥环中
• 🔄 Claude Desktop 启动时自动加载
• ⚡ 无需重复进行身份验证

📝 注意：完成初始设置后，你应该可以正常使用 Claude Desktop，无需执行任何额外配置步骤！

🎮 在 Claude Desktop 中使用

安装完成后，只需使用自然语言与 Claude 对话：

数据分析

• “有哪些表可用？” - 列出数据库表
• “有哪些 Databricks 目录可用？” - 浏览 Databricks 目录
• “显示 sales 目录中的架构” - 列出架构
• “分析 sales 表” - 获取表信息
• “显示收入最高的 10 种产品” - 查询数据

创建可视化图表

• “按地区创建销售额柱状图” - 生成图表
• “显示价格与数量之间的相关性” - 散点图
• “创建客户细分饼图” - 类别细分
• “可视化随时间变化的销售趋势” - 时间序列分析

数据库管理

DuckDB：

• “浏览 Downloads 文件夹中的数据库” - 交互式数据库浏览器
• “连接到 C:/path/to/mydata.duckdb” - 切换数据库
• “将 Downloads/sales.csv 加载为表 ‘sales’” - 导入数据

Databricks：

• “切换到 marketing 目录” - 浏览目录
• “列出 sales 目录中的架构” - 浏览架构
• “我连接的是哪个数据库？” - 连接信息

🔧 CLI 命令

此软件包包含功能强大的 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

📊 支持的图表类型

图表类型	用途	示例请求
条形图	比较类别	“按地区显示销售额”
折线图	显示随时间变化的趋势	“绘制每月收入”
散点图	探索关系	“价格与数量的关系”
饼图	显示占比	“客户细分情况”
直方图	分析分布	“订单金额分布”
箱线图	比较分布	“按类别显示价格范围”
热力图	显示相关性	“指标相关性矩阵”
面积图	累计趋势	“随时间变化的累计销售额”

🛠️ 故障排除

Claude Desktop 中出现“找不到服务”

# Check configuration status
mcp-viz status

# Reconfigure if needed
mcp-viz configure --force

# Restart Claude Desktop completely

“未知工具”错误

# Test server functionality
mcp-viz test

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

数据库问题

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

# Check current configuration
mcp-viz status

🔧 高级配置

自定义数据库路径

安装程序会提示你选择数据库位置，也可以自行指定：

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

多个数据库

你可以使用 Claude Desktop 轻松切换数据库：

• “浏览 Documents 文件夹中的数据库”
• “连接到 /path/to/another/database.duckdb”
• “我当前连接的是哪个数据库？”

💾 示例数据

🎯 内置示例数据

软件包会自动创建示例数据，包括：

• 销售数据 - 跨地区和产品的 365 天销售数据
• 客户数据 - 包含人口统计信息的 1000 条客户记录
• 产品数据 - 包含类别和定价信息的 100 种产品

🌟 其他示例数据库

想探索更多数据？看看这些高质量示例数据库：

TimeStored 示例 DuckDB 数据库

可用数据集包括：

• 金融数据 - 股票价格、交易数据、市场分析
• 纽约市出租车 - 真实的纽约市出租车行程记录，包含地理空间数据
• TPC-H 基准测试 - 标准数据库性能测试数据
• 电子商务 - 产品目录、订单、客户行为
• IoT 传感器数据 - 时间序列传感器读数和遥测数据

只需下载任意 .duckdb 文件并加载即可：

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

非常适合测试、学习和演示数据可视化功能！

🏗️ 开发环境设置

面向希望参与贡献的开发者：

# 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

详细说明请参阅开发指南。

❓ 常见问题

问：我每次都需要运行 mcp-viz databricks configure 吗？

答：不需要！ 初始设置时只需运行一次。之后：

• ✅ 凭据会安全存储并自动加载
• ✅ 只需打开 Claude Desktop 即可开始聊天
• ✅ 无需重复进行身份验证

问：如何知道 Databricks 是否仍处于连接状态？

答： 随时运行以下命令检查：

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

问：什么时候需要重新配置？

答： 仅在以下情况下需要：

• 访问令牌过期
• 更换 Databricks 工作区
• 切换到其他 SQL warehouse
• 凭据损坏（极少见）

问：我的凭据安全吗？

答： 是的！凭据会：

• 🔒 在磁盘上加密，或存储在系统钥匙串中
• 🚫 绝不会以纯文本形式存储，也不会出现在命令历史记录中
• ⚡ 需要时自动加载

问：我可以同时使用 DuckDB 和 Databricks 吗？

**答：**可以！服务会自动检测要使用的数据库类型：

• 配置 Databricks：mcp-viz databricks configure
• 配置 DuckDB：mcp-viz configure
• 服务会自动使用相应的数据库

📦 软件包信息

• PyPI：https://pypi.org/project/mcp-visualization-duckdb/
• 仓库：https://github.com/your-github-username/mcp-visualization-duckdb
• 许可证：MIT

🤝 参与贡献

欢迎贡献！此软件包采用便于开发的结构：

1. Fork 仓库
2. 创建功能分支
3. 进行修改
4. 运行测试：python test_package.py
5. 提交 pull request

🙏 致谢

• Anthropic 开发的 Model Context Protocol
• DuckDB，用于快速分析处理
• Plotly，用于交互式可视化
• Claude Desktop，提供出色的 AI 界面

---

准备好使用 Claude Desktop 改变数据分析方式了吗？

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

🎉 **就是这样！**开始与 Claude 聊聊你的数据吧！