Mcp Superset

mcp-superset

一个功能全面的 Model Context Protocol（MCP） 服务，可用于 Apache Superset。通过 137 个工具，让 AI 助手（Claude、GPT 等）全面控制你的 Superset 实例，包括仪表板、图表、数据集、SQL Lab、用户、角色、RLS 等。

与其他 Superset MCP 服务的对比

功能	mcp-superset	superset-mcp	superset-mcp (Winding2020)	superset-mcp-server
工具总数	137	60	31	4
语言	Python	Python	TypeScript	TypeScript
仪表板 CRUD	15 个工具	5	8	-
仪表板原生筛选器	5 个工具	-	-	-
图表 CRUD	11 个工具	5	7	-
数据库工具	18 个工具	14	1	1
数据集工具	11 个工具	3	7	-
SQL Lab	5 个工具	7	1	1
安全性（用户/角色）	26 个工具	2	-	-
行级安全性	5 个工具	-	-	-
组	9 个工具	-	-	-
权限审计	是	-	-	-
授予/撤销仪表板访问权限	是	-	-	-
自动同步 datasource_access	是	-	-	-
报告与注释	10 个工具	-	-	-
标签	7 个工具	7	-	-
资源导出/导入	是	-	-	-
安全性：确认标志	14 种	-	-	-
安全性：阻止 DDL/DML	是	-	-	-
安全性：保护系统角色	是	-	-	-
传输方式	HTTP、SSE、stdio	stdio	stdio	stdio
认证方式	JWT + 自动刷新 + CSRF	用户名/密码 + 令牌文件	用户名/密码或令牌	LDAP
Superset 版本	6.0.1	4.1.1	未指定	未指定
带参数的 CLI	--host --port --transport	-	-	-
PyPI 包	mcp-superset	superset-mcp	superset-mcp (npm)	-
支持 uvx	是	-	-	-
许可证	MIT	MIT	-	Apache 2.0
GitHub 星标数	新发布	170	21	5

主要差异：

• 唯一支持全面安全管理的 MCP 服务（用户、角色、RLS、组、权限审计）
• 唯一内置安全验证的服务（确认标志、阻止 DDL/DML）
• 唯一支持仪表板原生筛选器管理的服务
• 唯一支持自动同步 datasource_access的服务
• 唯一支持多种传输方式的服务（HTTP、SSE、stdio）
• 唯一支持可配置 CLI 的服务（--host、--port、--transport、--env-file）

功能

• 137 个 MCP 工具，覆盖完整的 Superset REST API
• 仪表板管理 — CRUD、复制、发布/取消发布、导出/导入、嵌入模式、原生筛选器
• 图表管理 — CRUD、复制、数据获取、导出/导入、缓存预热
• 数据库管理 — CRUD、连接测试、模式/表检查、SQL 验证
• 数据集管理 — CRUD、复制、模式刷新、导出/导入
• SQL Lab — 查询执行、格式化、成本估算、结果与 CSV 导出
• 安全性 — 用户、角色、权限、行级安全性（RLS）、组
• 访问控制自动化 — 授予/撤销仪表板访问权限，并自动同步数据源权限
• 审计 — 全面的权限矩阵（用户 x 仪表板 x 数据集 x RLS）
• 标签、报告、注释、已保存查询 — 完整的 CRUD
• 资源导出/导入 — 完整的实例备份与恢复
• 内置安全机制 — 破坏性操作的确认标志，阻止 SQL Lab 中的 DDL/DML
• JWT 身份验证，支持自动刷新令牌并处理 CSRF
• Streamable HTTP、SSE 和 stdio 传输方式

快速开始

安装

# From PyPI
pip install mcp-superset

# With uv (recommended)
uv pip install mcp-superset

# Run without installing (uvx)
uvx mcp-superset

配置

在当前目录中创建 .env 文件，或设置环境变量：

# Required
SUPERSET_BASE_URL=https://superset.example.com
SUPERSET_USERNAME=admin
SUPERSET_PASSWORD=your_password

# Optional
SUPERSET_AUTH_PROVIDER=db          # db (default) or ldap
SUPERSET_MCP_HOST=127.0.0.1       # Server host (default: 127.0.0.1)
SUPERSET_MCP_PORT=8001             # Server port (default: 8001)
SUPERSET_MCP_TRANSPORT=streamable-http  # streamable-http (default), sse, or stdio

Session-cookie authentication (SSO/OAuth)

当 Superset 位于 SSO（OAuth/OIDC/SAML）之后时，无法通过 REST API 使用密码登录。此时，请提供浏览器的 session cookie：

变量	描述
SUPERSET_SESSION_COOKIE	从浏览器复制的 session cookie 值。设置后，将使用此模式，而非用户名/密码。
SUPERSET_SESSION_COOKIE_NAME	Cookie 名称。默认为 session。

从浏览器开发者工具中复制 Cookie（Application → Cookies → 你的 Superset 域名 → session）。MCP 服务会在每次请求中发送此 Cookie， 并使用它获取 CSRF 令牌。服务端无法续期 session，因此 session 过期后， 你必须粘贴新的值并重启服务。

使用此模式前，建议检查以下两点：

• Cookie 名称不一定是 session。 在 superset_config.py 中设置 SESSION_COOKIE_NAME 的实例会使用其他名称（例如 s）。请使用开发者工具中显示的名称，并相应设置 SUPERSET_SESSION_COOKIE_NAME。
• 实例必须接受 /api/v1/ 上的 session 身份验证。 如果 REST API 配置为仅使用 JWT 身份验证，即使请求携带有效的 session cookie，仍会返回 401 {"msg": "Missing Authorization Header"}——刷新 Cookie 也无济于事，此时只能使用 JWT 模式。

请将 Cookie 视为凭据：在 session 有效期内，它授予对你的 Superset 账户的完整访问权限。请将它保存在 .env（该文件已加入 gitignore）中， 不要放入 shell 历史记录或已提交的配置中。

运行

# Using CLI (after pip install)
mcp-superset

# Run without installing
uvx mcp-superset

# Using Python module
python -m mcp_superset

# With uv from source
uv run mcp-superset

# With custom settings
mcp-superset --host 0.0.0.0 --port 9000 --transport sse

# With custom .env file
mcp-superset --env-file /path/to/.env

# Using stdio transport (for Claude Desktop, Cursor, etc.)
mcp-superset --transport stdio

CLI 选项

选项	默认值	环境变量	描述
--host	127.0.0.1	SUPERSET_MCP_HOST	服务绑定地址
--port	8001	SUPERSET_MCP_PORT	服务绑定端口
--transport	streamable-http	SUPERSET_MCP_TRANSPORT	传输方式：streamable-http、sse、stdio
--env-file	自动检测	—	.env 文件的路径
--version	—	—	显示版本并退出

连接到 MCP 客户端

Claude Code

添加到项目的 .mcp.json 中：

{
  "mcpServers": {
    "superset": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    }
  }
}

然后启动服务：mcp-superset 或 uvx mcp-superset。

Claude Desktop

添加到 claude_desktop_config.json 中：

{
  "mcpServers": {
    "superset": {
      "command": "uvx",
      "args": ["mcp-superset", "--transport", "stdio"],
      "env": {
        "SUPERSET_BASE_URL": "https://superset.example.com",
        "SUPERSET_USERNAME": "admin",
        "SUPERSET_PASSWORD": "your_password"
      }
    }
  }
}

Cursor / Windsurf

{
  "mcpServers": {
    "superset": {
      "command": "uvx",
      "args": ["mcp-superset", "--transport", "stdio"],
      "env": {
        "SUPERSET_BASE_URL": "https://superset.example.com",
        "SUPERSET_USERNAME": "admin",
        "SUPERSET_PASSWORD": "your_password"
      }
    }
  }
}

其他 MCP 客户端

任何兼容 MCP 的客户端都可以通过以下方式连接：

• Streamable HTTP：http://<host>:<port>/mcp
• SSE：http://<host>:<port>/sse
• stdio：将管道连接到 mcp-superset --transport stdio

可用工具（137）

仪表板（15 个工具）

工具	描述
superset_dashboard_list	列出仪表板，支持筛选和分页
superset_dashboard_get	按 ID 获取仪表板详情
superset_dashboard_create	创建仪表板
superset_dashboard_update	更新仪表板属性
superset_dashboard_delete	删除仪表板（需要确认）
superset_dashboard_copy	复制仪表板
superset_dashboard_publish	发布仪表板草稿
superset_dashboard_unpublish	取消发布仪表板
superset_dashboard_charts	列出仪表板中的图表
superset_dashboard_datasets	列出仪表板使用的数据集
superset_dashboard_export	将仪表板导出为 ZIP（base64）
superset_dashboard_import	从 ZIP 文件导入仪表板
superset_dashboard_embedded_get	获取嵌入式配置
superset_dashboard_embedded_set	启用嵌入模式并设置允许的域名
superset_dashboard_embedded_delete	禁用嵌入模式

仪表板筛选器（5 个工具）

工具	描述
superset_dashboard_filter_list	列出仪表板上的原生筛选器
superset_dashboard_filter_add	添加原生筛选器（自动生成正确的 ID 格式）
superset_dashboard_filter_update	更新现有原生筛选器
superset_dashboard_filter_delete	移除原生筛选器（需要确认）
superset_dashboard_filter_reset	移除所有筛选器（需要确认）

图表（11 个工具）

工具	描述
superset_chart_list	列出图表，支持筛选和分页
superset_chart_get	根据 ID 获取图表详情
superset_chart_create	创建新图表
superset_chart_update	更新图表属性
superset_chart_delete	删除图表（需要确认）
superset_chart_copy	复制图表
superset_chart_data	执行图表查询并获取数据
superset_chart_get_data	获取已保存图表的数据
superset_chart_export	将图表导出为 ZIP（base64）
superset_chart_import	从 ZIP 文件导入图表
superset_chart_cache_warmup	预热图表缓存

数据库（18 个工具）

工具	描述
superset_database_list	列出数据库连接
superset_database_get	获取数据库详情
superset_database_create	注册新的数据库连接
superset_database_update	更新数据库设置
superset_database_delete	移除数据库（需要确认）
superset_database_test_connection	测试数据库连通性
superset_database_schemas	列出数据库中的架构
superset_database_tables	列出架构中的表
superset_database_catalogs	列出目录（适用于多目录数据库）
superset_database_connection_info	获取连接字符串信息
superset_database_function_names	列出可用的 SQL 函数
superset_database_related_objects	查找使用此数据库的图表/数据集
superset_database_validate_sql	验证 SQL 语法
superset_database_validate_parameters	验证连接参数
superset_database_select_star	为表生成 SELECT * 查询
superset_database_table_metadata	获取表的列和索引元数据
superset_database_export	将数据库配置导出为 ZIP
superset_database_available_engines	列出支持的数据库引擎

数据集（11 个工具）

工具	描述
superset_dataset_list	列出数据集，支持筛选
superset_dataset_get	获取数据集详情，包括列和指标
superset_dataset_create	根据表或 SQL 查询创建数据集
superset_dataset_update	更新数据集属性
superset_dataset_delete	删除数据集（需要确认）
superset_dataset_duplicate	复制数据集
superset_dataset_refresh_schema	从数据源刷新列
superset_dataset_related_objects	查找使用此数据集的图表
superset_dataset_export	将数据集导出为 ZIP
superset_dataset_import	从 ZIP 导入数据集
superset_dataset_get_or_create	获取现有数据集或创建新数据集

SQL Lab 与查询（13 个工具）

工具	描述
superset_sqllab_execute	执行 SQL 查询（仅限 SELECT）
superset_sqllab_format_sql	格式化／美化 SQL
superset_sqllab_results	获取已完成查询的结果
superset_sqllab_estimate_cost	估算查询执行成本
superset_sqllab_export_csv	将查询结果导出为 CSV
superset_query_list	列出已执行的查询
superset_query_get	获取查询详情和结果
superset_query_stop	停止正在运行的查询
superset_saved_query_list	列出已保存的查询
superset_saved_query_create	保存新查询
superset_saved_query_get	获取已保存的查询详情
superset_saved_query_update	更新已保存的查询
superset_saved_query_delete	删除已保存的查询（需要确认）

安全与访问控制（26 个工具）

工具	描述
superset_get_current_user	获取当前已认证用户的信息
superset_get_current_user_roles	获取当前用户的角色
superset_user_list	筛选并列出用户
superset_user_get	获取用户详情
superset_user_create	创建新用户
superset_user_update	更新用户属性
superset_user_delete	删除用户（需要确认）
superset_role_list	列出角色
superset_role_get	获取角色详情
superset_role_create	创建新角色
superset_role_update	更新角色名称／描述
superset_role_delete	删除角色（需要确认，系统角色除外）
superset_permission_list	列出所有可用权限
superset_role_permissions_get	获取分配给角色的权限
superset_role_permission_add	设置角色权限（完全替换，需要确认）
superset_role_copy_permissions	将一个角色的所有权限复制到另一个角色
superset_dashboard_grant_role_access	授予角色访问仪表板及其数据集的权限
superset_dashboard_revoke_role_access	撤销角色对仪表板数据集的访问权限
superset_bulk_user_role_add	为多个用户添加角色（按 ID 或当前角色）
superset_bulk_user_role_remove	为多个用户移除角色
superset_bulk_user_role_replace	为所有匹配的用户将一个角色替换为另一个角色
superset_rls_list	列出行级安全规则
superset_rls_get	获取 RLS 规则详情
superset_rls_create	创建 RLS 规则
superset_rls_update	更新 RLS 规则（需要同时提供角色和表）
superset_rls_delete	删除 RLS 规则（需要确认）

群组（9 个工具）

工具	描述
superset_group_list	列出群组
superset_group_get	获取包含成员和角色的群组详情
superset_group_create	创建新群组
superset_group_update	更新群组名称
superset_group_delete	删除群组
superset_group_add_users	将用户添加到群组
superset_group_remove_users	从群组中移除用户
superset_group_add_roles	将角色添加到群组
superset_group_remove_roles	从群组中移除角色

标签（7 个工具）

工具	描述
superset_tag_list	列出标签
superset_tag_get	获取标签详情
superset_tag_create	创建标签（可选绑定到对象）
superset_tag_update	更新标签
superset_tag_delete	删除标签（需要确认）
superset_tag_get_objects	列出与标签关联的对象
superset_tag_bulk_create	一次创建多个标签

系统与报告（21 个工具）

工具	描述
superset_report_list	列出计划报告
superset_report_get	获取报告详情
superset_report_create	创建计划报告
superset_report_update	更新报告
superset_report_delete	删除报告（需要确认）
superset_annotation_layer_list	列出注释图层
superset_annotation_layer_get	获取注释图层详情
superset_annotation_layer_create	创建注释图层
superset_annotation_layer_update	更新注释图层
superset_annotation_layer_delete	删除注释图层（需要确认）
superset_annotation_list	列出图层中的注释
superset_annotation_get	获取注释详情
superset_annotation_create	创建注释
superset_annotation_update	更新注释
superset_annotation_delete	删除注释（需要确认）
superset_recent_activity	获取近期用户活动
superset_log_list	获取审计日志
superset_get_menu	获取 Superset 菜单结构
superset_get_base_url	获取已配置的 Superset 基础 URL
superset_assets_export	将所有 Superset 资源导出为 ZIP
superset_assets_import	从 ZIP 文件导入资源

审计（1 个工具）

工具	描述
superset_permissions_audit	生成全面的权限矩阵

安全功能

该服务内置了全面的防护措施，以防止意外的数据丢失或配置错误。

确认标志

破坏性操作需要显式的确认参数：

操作	必需标志	显示内容
删除仪表板	confirm_delete=True	仪表板名称、slug、图表数量
删除图表	confirm_delete=True	关联的仪表板
删除数据集	confirm_delete=True	受影响的图表和仪表板
删除数据库	confirm_delete=True	受影响的数据集和图表
删除 RLS 规则	confirm_delete=True	子句、角色、数据集
删除角色	confirm_delete=True	阻止删除系统角色
删除用户	confirm_delete=True	阻止删除服务账户
更新图表参数	confirm_params_replace=True	—
更新数据集列	confirm_columns_replace=True	—
更新数据库 URI	confirm_uri_change=True	受影响的图表/仪表板
更新用户角色	confirm_roles_replace=True	当前角色
设置角色权限	confirm_full_replace=True	—
授予仪表板访问权限	confirm_grant=True	试运行结果
撤销仪表板访问权限	confirm_revoke=True	试运行结果
批量为用户添加角色	confirm=True	用户数量、示例列表
批量移除用户角色	confirm=True	用户数量，防止移除最后一个角色
批量替换角色	confirm=True	旧/新角色名称、用户数量
复制角色权限	confirm=True	源/目标权限数量

自动防护

• 阻止 DDL/DML — SQL Lab 会拒绝 DROP、DELETE、UPDATE、INSERT、TRUNCATE、ALTER、CREATE、GRANT、REVOKE（检查前会移除 SQL 注释）
• 系统角色保护 — 无法删除 Admin、Alpha、Gamma、Public 角色
• 服务账户保护 — 无法删除 MCP 服务用户
• RLS 安全性 — rls_update 要求同时提供 roles 和 tables，以防止无提示的数据清除
• 原生筛选器 ID — 自动按 NATIVE_FILTER-<uuid> 格式生成
• 图表验证 — 拒绝缺少 granularity_sqla 的图表（仪表板时间筛选器必需）
• 自动同步 — 仪表板角色变更时，会自动同步 datasource_access 权限

架构

superset-mcp/
├── pyproject.toml              # Package configuration
├── .env.example                # Environment variable template
├── LICENSE                     # MIT License
├── README.md                   # This file
├── README_RU.md                # Russian documentation
├── CHANGELOG.md                # Version history
└── src/mcp_superset/
    ├── __init__.py             # Package init with __version__
    ├── __main__.py             # CLI entry point with argparse
    ├── server.py               # FastMCP server setup and configuration
    ├── auth.py                 # JWT authentication (login, refresh, CSRF)
    ├── client.py               # HTTP client (auto-auth, retry, RISON pagination)
    ├── models.py               # Pydantic models
    └── tools/
        ├── __init__.py         # register_all_tools()
        ├── helpers.py          # Auto-sync datasource_access logic
        ├── dashboards.py       # Dashboard + filter tools (20)
        ├── charts.py           # Chart tools (11)
        ├── databases.py        # Database tools (18)
        ├── datasets.py         # Dataset tools (11)
        ├── queries.py          # SQL Lab + saved query tools (13)
        ├── security.py         # User, role, permission, RLS, bulk operations (26)
        ├── groups.py           # Group management tools (9)
        ├── audit.py            # Permissions audit tool (1)
        ├── tags.py             # Tag tools (7)
        └── system.py           # Reports, annotations, logs, assets (21)

Superset 兼容性

• 测试版本：Apache Superset 6.0.1
• 身份验证：JWT（推荐）——Superset 未实现 API Key（sst_*）
• 所需 Superset 用户：Admin 角色（用于完整 API 访问权限）

推荐的 Superset 配置

添加到你的 superset_config.py 中：

from datetime import timedelta

# Increase JWT token lifetime (default is 15 min)
JWT_ACCESS_TOKEN_EXPIRES = timedelta(hours=1)
JWT_REFRESH_TOKEN_EXPIRES = timedelta(days=30)

# Max API page size
FAB_API_MAX_PAGE_SIZE = 100

开发

设置

git clone https://github.com/bintocher/mcp-superset.git
cd superset-mcp

# Create virtual environment and install in editable mode
uv venv
uv pip install -e ".[dev]"

# Copy and configure .env
cp .env.example .env
# Edit .env with your Superset credentials

本地运行

# Run from source
uv run python -m mcp_superset

# Or with CLI
uv run mcp-superset --port 8001

运行测试

uv run python test_all_tools.py

已知的 Superset API 特性

MCP 服务会自动处理这些问题，但调试时了解一下会很有帮助：

特性	详细信息
RISON 分页	Superset 会忽略作为查询参数的 page/page_size；必须在 q 参数中使用 RISON
需要 CSRF	所有 POST/PUT/DELETE 请求都需要 X-CSRFToken 标头和会话 Cookie
需要 Referer	SQL Lab 在没有 Referer 标头时会返回 403
Tag API 返回 {}	创建 Tag 时不会返回 ID；必须查询列表
更新 Tag 需要 name	此字段为必填项，即使名称未更改也必须提供
角色权限采用替换方式	POST /security/roles/{id}/permissions 会替换所有权限
更新 RLS 会替换字段	PUT /rowlevelsecurity/{id} 会替换所有提供的字段
更新 Dataset 列	使用 columns 调用 PUT /dataset/{id} 会替换所有列
复制 Dashboard	需要提供 json_metadata（可以是 "{}"）
原生筛选器 ID	必须采用 NATIVE_FILTER-<uuid> 格式
filter_time 需要 granularity_sqla	不包含此字段的图表会静默忽略时间筛选器
数字格式	SMART_NUMBER 会缩写数字；要精确显示，请使用 ,d 或 ,.2f

许可证

MIT — Stanislav Chernov（@bintocher）