当前位置：首页 > news >正文

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

news 2025/8/27 10:04:41

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