【服务器】Apache Superset MCP接入与使用

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 桌面端）

bash 复制代码

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

方式 2：手动安装

bash 复制代码

# 克隆仓库
git clone https://github.com/aptro/superset-mcp.git
cd superset-mcp

# 安装依赖
uv pip install .

3.2 环境配置

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

env 复制代码

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

3.3 启动 Superset 实例

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

bash 复制代码

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 基础使用流程

python 复制代码

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 asyncio
    asyncio.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 交互体验，以及增强安全性和企业级特性。