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

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

到此这篇关于【服务器】Apache Superset MCP接入与使用的文章就介绍到这了,更多相关Apache Superset MCP使用内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

最新评论