1. 概述

Apache Superset MCP 集成（superset-mcp）是一个基于 Model Control Protocol（MCP）的服务器工具，旨在实现 AI 代理与 Apache Superset 的程序化交互。该项目通过提供标准化的工具接口，使 AI 助手（如 Claude）能够连接并控制 Superset 实例，实现数据可视化、报表生成、SQL 查询等操作的自动化。

项目仓库：https://github.com/aptro/superset-mcp

2. 核心功能与架构

2.1 核心定位

superset-mcp 作为 Superset 与 AI 代理之间的中间层，主要解决以下问题：

• 提供标准化接口，使 AI 代理能够理解和操作 Superset
• 处理认证与权限管理
• 封装 Superset API 为更适合 AI 调用的工具集
• 实现令牌自动刷新与会话管理

2.2 技术架构

• 基础框架：基于 FastAPI 构建的 MCP 服务器
• 通信层：使用 httpx 处理与 Superset 的 HTTP 通信
• 认证机制：基于令牌的认证系统，支持自动刷新
• 工具抽象：将 Superset 功能封装为可调用的 MCP 工具
• 配置管理：通过环境变量和 .env 文件管理连接参数

3. 安装与配置

3.1 安装方式

方式 1：通过 Smithery 安装（推荐用于 Claude 桌面端）

npx -y @smithery/cli install @aptro/superset-mcp --client claude

方式 2：手动安装

# 克隆仓库
git clone https://github.com/aptro/superset-mcp.git
cd superset-mcp# 安装依赖
uv pip install .

3.2 环境配置

创建 .env 文件配置 Superset 连接信息：

SUPERSET_BASE_URL=http://localhost:8088  # Superset 实例地址
SUPERSET_USERNAME=admin                  # Superset 用户名
SUPERSET_PASSWORD=admin                  # Superset 密码

3.3 启动 Superset 实例

推荐使用 4.1.1 版本（经测试兼容）：

git clone --branch 4.1.1 --depth 1 https://github.com/apache/superset && \
cd superset && \
docker compose -f docker-compose-image-tag.yml up

4. 核心工具集

superset-mcp 提供了丰富的 MCP 工具，覆盖 Superset 主要功能领域，以下是分类说明：

4.1 认证相关工具

• superset_auth_check_token_validity - 验证当前访问令牌有效性
• superset_auth_refresh_token - 刷新访问令牌
• superset_auth_authenticate_user - 用户认证

4.2 仪表盘操作

• superset_dashboard_list - 列出所有仪表盘
• superset_dashboard_get_by_id - 获取特定仪表盘详情
• superset_dashboard_create - 创建新仪表盘
• superset_dashboard_update - 更新现有仪表盘
• superset_dashboard_delete - 删除仪表盘

4.3 图表管理

• superset_chart_list - 列出所有图表
• superset_chart_get_by_id - 获取特定图表详情
• superset_chart_create - 创建新图表
• superset_chart_update - 更新现有图表
• superset_chart_delete - 删除图表

4.4 数据库与数据集

• superset_database_list - 列出所有数据库连接
• superset_database_get_tables - 获取数据库中的表
• superset_dataset_list - 列出所有数据集
• superset_dataset_create - 创建新数据集

4.5 SQL 实验室功能

• superset_sqllab_execute_query - 执行 SQL 查询
• superset_sqllab_format_sql - 格式化 SQL 语句
• superset_sqllab_get_results - 获取查询结果
• superset_sqllab_estimate_query_cost - 估算查询成本
• superset_sqllab_export_query_results - 导出查询结果为 CSV

4.6 其他工具

• 探索工具（superset_explore_*）- 图表探索与 permalink 管理
• 标签管理（superset_tag_*）- 标签的创建、删除与关联
• 用户信息（superset_user_*）- 获取当前用户信息与角色
• 系统信息（superset_menu_get, superset_config_get_base_url）

5. 使用示例

5.1 基础使用流程

from mcp.server.fastmcp import Context
from superset_mcp.main import mcp, superset_dashboard_list, superset_sqllab_execute_query# 初始化上下文（实际使用中由 MCP 服务器管理）
class MockContext:def __init__(self, lifespan_context):self.request_context = type('', (), {'lifespan_context': lifespan_context})()# 列出所有仪表盘
async def list_dashboards(ctx: Context):result = await superset_dashboard_list(ctx)print("所有仪表盘：", result)# 执行 SQL 查询
async def run_sql_query(ctx: Context, database_id: int, sql: str):result = await superset_sqllab_execute_query(ctx,database_id=database_id,sql=sql)print("查询结果：", result)# 运行示例（需在异步环境中执行）
if __name__ == "__main__":import asyncioasyncio.run(list_dashboards(MockContext(mcp.lifespan_context)))asyncio.run(run_sql_query(MockContext(mcp.lifespan_context), 1, "SELECT * FROM users LIMIT 10"))

5.2 与 Claude 交互示例

通过自然语言指令使用 Superset 功能：

• “列出我所有的仪表盘”
• “运行这个 SQL 查询：SELECT COUNT(*) FROM orders”
• “格式化这段 SQL：SELECT id,name,age FROM users WHERE age>21”
• “创建一个新的柱状图，展示每月销售额”

6. 安全性考量

• 凭据存储：Superset 用户名和密码仅存储在本地 .env 文件中
• 令牌管理：访问令牌存储在项目目录的 .superset_token 文件中
• 通信安全：所有认证操作直接在 MCP 服务器与 Superset 实例之间进行
• 第三方隔离：不会向 Claude 或其他第三方传输任何凭据信息
• 生产建议：生产环境中应使用更安全的认证方法，而非基本用户名/密码认证

7. 故障排除

• 认证问题：检查 .env 文件中的凭据是否正确
• 连接问题：确认 Superset 实例正在运行且 URL 正确
• 版本兼容：确保使用兼容的 Superset 版本（推荐 4.1.1）
• 端口冲突：检查 MCP 服务器端口是否被其他应用占用

8. 许可证与贡献

• 许可证：项目采用 MIT 许可证，允许自由使用、复制、修改和分发
• 贡献方式：欢迎通过提交 Pull Request 参与项目开发

9. 总结

superset-mcp 为 Apache Superset 提供了强大的 AI 集成能力，通过标准化的 MCP 工具集，使 AI 代理能够以自然语言交互的方式操作 Superset。该项目降低了数据分析与可视化的技术门槛，特别适合需要快速生成报表、执行查询和管理数据资产的场景。

未来发展方向可能包括扩展更多 Superset 功能、优化 AI 交互体验，以及增强安全性和企业级特性。