bintocher/mcp-superset

Бесплатно

Full-featured Apache Superset MCP server with 135+ tools for dashboards, charts, datasets, SQL Lab, security (users, roles, RLS, groups), permissions audit, and

автор: bintocher

GitHub

Описание

Full-featured Apache Superset MCP server with 135+ tools for dashboards, charts, datasets, SQL Lab, security (users, roles, RLS, groups), permissions audit, and 30+ built-in safety validations. Supports HTTP, SSE, and stdio transports.

README

PyPI version PyPI downloads Python 3.12+ License: MIT CI CodeQL

Superset 6.0.1 MCP Typed Ruff uv Tools: 137 GitHub stars

A comprehensive Model Context Protocol (MCP) server for Apache Superset. Gives AI assistants (Claude, GPT, etc.) full control over your Superset instance — dashboards, charts, datasets, SQL Lab, users, roles, RLS, and more — through 137 tools.

Comparison with Other Superset MCP Servers

Feature	mcp-superset	superset-mcp	superset-mcp (Winding2020)	superset-mcp-server
Total tools	137	60	31	4
Language	Python	Python	TypeScript	TypeScript
Dashboard CRUD	15 tools	5	8	-
Dashboard native filters	5 tools	-	-	-
Chart CRUD	11 tools	5	7	-
Database tools	18 tools	14	1	1
Dataset tools	11 tools	3	7	-
SQL Lab	5 tools	7	1	1
Security (users/roles)	26 tools	2	-	-
Row Level Security	5 tools	-	-	-
Groups	9 tools	-	-	-
Permissions audit	yes	-	-	-
Dashboard access grant/revoke	yes	-	-	-
Auto datasource_access sync	yes	-	-	-
Reports & annotations	10 tools	-	-	-
Tags	7 tools	7	-	-
Asset export/import	yes	-	-	-
Safety: confirmation flags	14 types	-	-	-
Safety: DDL/DML blocking	yes	-	-	-
Safety: system role protection	yes	-	-	-
Transport	HTTP, SSE, stdio	stdio	stdio	stdio
Auth method	JWT + auto-refresh + CSRF	Username/password + token file	Username/password or token	LDAP
Superset versions	6.0.1	4.1.1	not specified	not specified
CLI with args	`--host --port --transport`	-	-	-
PyPI package	`mcp-superset`	`superset-mcp`	`superset-mcp` (npm)	-
uvx support	yes	-	-	-
License	MIT	MIT	-	Apache 2.0
GitHub stars	new	170	21	5

Key differentiators:

Only MCP server with full security management (users, roles, RLS, groups, permissions audit)
Only one with built-in safety validations (confirmation flags, DDL/DML blocking)
Only one with dashboard native filter management
Only one with automatic datasource_access synchronization
Only one with multiple transport options (HTTP, SSE, stdio)
Only one with configurable CLI (--host, --port, --transport, --env-file)

Features

137 MCP tools covering the complete Superset REST API
Dashboard management — CRUD, copy, publish/unpublish, export/import, embedded mode, native filters
Chart management — CRUD, copy, data retrieval, export/import, cache warmup
Database management — CRUD, connection testing, schema/table introspection, SQL validation
Dataset management — CRUD, duplicate, schema refresh, export/import
SQL Lab — query execution, formatting, cost estimation, results & CSV export
Security — users, roles, permissions, Row Level Security (RLS), groups
Access control automation — grant/revoke dashboard access with automatic datasource permission sync
Audit — comprehensive permissions matrix (user x dashboards x datasets x RLS)
Tags, reports, annotations, saved queries — full CRUD
Asset export/import — full instance backup and restore
Built-in safety — confirmation flags for destructive operations, DDL/DML blocking in SQL Lab
JWT authentication with automatic token refresh and CSRF handling
Streamable HTTP, SSE, and stdio transports

Quick Start

Installation

# From PyPI
pip install mcp-superset

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

# Run without installing (uvx)
uvx mcp-superset

Configuration

Create a .env file in the current directory, or set environment variables:

# 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

Running

# 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 Options

Option	Default	Env Variable	Description
`--host`	`127.0.0.1`	`SUPERSET_MCP_HOST`	Server bind address
`--port`	`8001`	`SUPERSET_MCP_PORT`	Server bind port
`--transport`	`streamable-http`	`SUPERSET_MCP_TRANSPORT`	Transport: `streamable-http`, `sse`, `stdio`
`--env-file`	auto-detect	—	Path to `.env` file
`--version`	—	—	Show version and exit

Connecting to MCP Clients

Claude Code

Add to your project's .mcp.json:

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

Then start the server: mcp-superset or uvx mcp-superset.

Claude Desktop

Add to 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"
      }
    }
  }
}

Other MCP Clients

Any MCP-compatible client can connect via:

Streamable HTTP: http://<host>:<port>/mcp
SSE: http://<host>:<port>/sse
stdio: pipe to mcp-superset --transport stdio

Available Tools (137)

Dashboards (15 tools)

Tool	Description
`superset_dashboard_list`	List dashboards with filtering and pagination
`superset_dashboard_get`	Get dashboard details by ID
`superset_dashboard_create`	Create a new dashboard
`superset_dashboard_update`	Update dashboard properties
`superset_dashboard_delete`	Delete a dashboard (requires confirmation)
`superset_dashboard_copy`	Duplicate a dashboard
`superset_dashboard_publish`	Publish a draft dashboard
`superset_dashboard_unpublish`	Unpublish a dashboard
`superset_dashboard_charts`	List charts in a dashboard
`superset_dashboard_datasets`	List datasets used by a dashboard
`superset_dashboard_export`	Export dashboard as ZIP (base64)
`superset_dashboard_import`	Import dashboard from ZIP file
`superset_dashboard_embedded_get`	Get embedded configuration
`superset_dashboard_embedded_set`	Enable embedded mode with allowed domains
`superset_dashboard_embedded_delete`	Disable embedded mode

Dashboard Filters (5 tools)

Tool	Description
`superset_dashboard_filter_list`	List native filters on a dashboard
`superset_dashboard_filter_add`	Add a native filter (auto-generates correct ID format)
`superset_dashboard_filter_update`	Update an existing native filter
`superset_dashboard_filter_delete`	Remove a native filter (requires confirmation)
`superset_dashboard_filter_reset`	Remove all filters (requires confirmation)

Charts (11 tools)

Tool	Description
`superset_chart_list`	List charts with filtering and pagination
`superset_chart_get`	Get chart details by ID
`superset_chart_create`	Create a new chart
`superset_chart_update`	Update chart properties
`superset_chart_delete`	Delete a chart (requires confirmation)
`superset_chart_copy`	Duplicate a chart
`superset_chart_data`	Execute chart query and get data
`superset_chart_get_data`	Get data from a saved chart
`superset_chart_export`	Export chart as ZIP (base64)
`superset_chart_import`	Import chart from ZIP file
`superset_chart_cache_warmup`	Warm up chart cache

Databases (18 tools)

Tool	Description
`superset_database_list`	List database connections
`superset_database_get`	Get database details
`superset_database_create`	Register a new database connection
`superset_database_update`	Update database settings
`superset_database_delete`	Remove a database (requires confirmation)
`superset_database_test_connection`	Test database connectivity
`superset_database_schemas`	List schemas in a database
`superset_database_tables`	List tables in a schema
`superset_database_catalogs`	List catalogs (for multi-catalog databases)
`superset_database_connection_info`	Get connection string info
`superset_database_function_names`	List available SQL functions
`superset_database_related_objects`	Find charts/datasets using this database
`superset_database_validate_sql`	Validate SQL syntax
`superset_database_validate_parameters`	Validate connection parameters
`superset_database_select_star`	Generate SELECT * query for a table
`superset_database_table_metadata`	Get table column and index metadata
`superset_database_export`	Export database config as ZIP
`superset_database_available_engines`	List supported database engines

Datasets (11 tools)

Tool	Description
`superset_dataset_list`	List datasets with filtering
`superset_dataset_get`	Get dataset details including columns and metrics
`superset_dataset_create`	Create a dataset from a table or SQL query
`superset_dataset_update`	Update dataset properties
`superset_dataset_delete`	Delete a dataset (requires confirmation)
`superset_dataset_duplicate`	Duplicate a dataset
`superset_dataset_refresh_schema`	Refresh columns from source
`superset_dataset_related_objects`	Find charts using this dataset
`superset_dataset_export`	Export dataset as ZIP
`superset_dataset_import`	Import dataset from ZIP
`superset_dataset_get_or_create`	Get existing or create new dataset

SQL Lab & Queries (13 tools)

Tool	Description
`superset_sqllab_execute`	Execute a SQL query (SELECT only)
`superset_sqllab_format_sql`	Format/beautify SQL
`superset_sqllab_results`	Fetch results of a completed query
`superset_sqllab_estimate_cost`	Estimate query execution cost
`superset_sqllab_export_csv`	Export query results as CSV
`superset_query_list`	List executed queries
`superset_query_get`	Get query details and results
`superset_query_stop`	Stop a running query
`superset_saved_query_list`	List saved queries
`superset_saved_query_create`	Save a new query
`superset_saved_query_get`	Get saved query details
`superset_saved_query_update`	Update a saved query
`superset_saved_query_delete`	Delete a saved query (requires confirmation)

Security & Access Control (26 tools)

Tool	Description
`superset_get_current_user`	Get current authenticated user info
`superset_get_current_user_roles`	Get roles of current user
`superset_user_list`	List users with filtering
`superset_user_get`	Get user details
`superset_user_create`	Create a new user
`superset_user_update`	Update user properties
`superset_user_delete`	Delete a user (requires confirmation)
`superset_role_list`	List roles
`superset_role_get`	Get role details
`superset_role_create`	Create a new role
`superset_role_update`	Update role name/description
`superset_role_delete`	Delete a role (requires confirmation, blocks system roles)
`superset_permission_list`	List all available permissions
`superset_role_permissions_get`	Get permissions assigned to a role
`superset_role_permission_add`	Set role permissions (full replacement, requires confirmation)
`superset_role_copy_permissions`	Copy all permissions from one role to another
`superset_dashboard_grant_role_access`	Grant a role access to dashboard and its datasets
`superset_dashboard_revoke_role_access`	Revoke a role's access to dashboard datasets
`superset_bulk_user_role_add`	Add a role to multiple users (by IDs or by current role)
`superset_bulk_user_role_remove`	Remove a role from multiple users
`superset_bulk_user_role_replace`	Replace one role with another for all matching users
`superset_rls_list`	List Row Level Security rules
`superset_rls_get`	Get RLS rule details
`superset_rls_create`	Create an RLS rule
`superset_rls_update`	Update an RLS rule (requires both roles and tables)
`superset_rls_delete`	Delete an RLS rule (requires confirmation)

Groups (9 tools)

Tool	Description
`superset_group_list`	List groups
`superset_group_get`	Get group details with members and roles
`superset_group_create`	Create a new group
`superset_group_update`	Update group name
`superset_group_delete`	Delete a group
`superset_group_add_users`	Add users to a group
`superset_group_remove_users`	Remove users from a group
`superset_group_add_roles`	Add roles to a group
`superset_group_remove_roles`	Remove roles from a group

Tags (7 tools)

Tool	Description
`superset_tag_list`	List tags
`superset_tag_get`	Get tag details
`superset_tag_create`	Create a tag (optionally bind to objects)
`superset_tag_update`	Update a tag
`superset_tag_delete`	Delete a tag (requires confirmation)
`superset_tag_get_objects`	List objects associated with a tag
`superset_tag_bulk_create`	Create multiple tags at once

System & Reports (21 tools)

Tool	Description
`superset_report_list`	List scheduled reports
`superset_report_get`	Get report details
`superset_report_create`	Create a scheduled report
`superset_report_update`	Update a report
`superset_report_delete`	Delete a report (requires confirmation)
`superset_annotation_layer_list`	List annotation layers
`superset_annotation_layer_get`	Get annotation layer details
`superset_annotation_layer_create`	Create an annotation layer
`superset_annotation_layer_update`	Update an annotation layer
`superset_annotation_layer_delete`	Delete an annotation layer (requires confirmation)
`superset_annotation_list`	List annotations in a layer
`superset_annotation_get`	Get annotation details
`superset_annotation_create`	Create an annotation
`superset_annotation_update`	Update an annotation
`superset_annotation_delete`	Delete an annotation (requires confirmation)
`superset_recent_activity`	Get recent user activity
`superset_log_list`	Get audit logs
`superset_get_menu`	Get Superset menu structure
`superset_get_base_url`	Get configured Superset base URL
`superset_assets_export`	Export all Superset assets as ZIP
`superset_assets_import`	Import assets from ZIP file

Audit (1 tool)

Tool	Description
`superset_permissions_audit`	Generate comprehensive permissions matrix

Safety Features

The server includes extensive built-in protections to prevent accidental data loss or misconfiguration.

Confirmation Flags

Destructive operations require explicit confirmation parameters:

Operation	Required Flag	What It Shows
Delete dashboard	`confirm_delete=True`	Dashboard name, slug, chart count
Delete chart	`confirm_delete=True`	Linked dashboards
Delete dataset	`confirm_delete=True`	Affected charts and dashboards
Delete database	`confirm_delete=True`	Affected datasets, charts
Delete RLS rule	`confirm_delete=True`	Clause, roles, datasets
Delete role	`confirm_delete=True`	Blocks system roles
Delete user	`confirm_delete=True`	Blocks service account deletion
Update chart params	`confirm_params_replace=True`	—
Update dataset columns	`confirm_columns_replace=True`	—
Update database URI	`confirm_uri_change=True`	Affected charts/dashboards
Update user roles	`confirm_roles_replace=True`	Current roles
Set role permissions	`confirm_full_replace=True`	—
Grant dashboard access	`confirm_grant=True`	Dry-run results
Revoke dashboard access	`confirm_revoke=True`	Dry-run results
Bulk add role to users	`confirm=True`	User count, sample list
Bulk remove role from users	`confirm=True`	User count, prevents last role removal
Bulk replace role	`confirm=True`	Old/new role names, user count
Copy role permissions	`confirm=True`	Source/target permission counts

Automatic Protections

DDL/DML blocking — SQL Lab rejects DROP, DELETE, UPDATE, INSERT, TRUNCATE, ALTER, CREATE, GRANT, REVOKE (SQL comments are stripped before checking)
System role protection — cannot delete Admin, Alpha, Gamma, Public roles
Service account protection — cannot delete the MCP service user
RLS safety — rls_update requires both roles and tables to prevent silent data wipe
Native filter IDs — automatically generated in NATIVE_FILTER-<uuid> format
Chart validation — rejects charts without granularity_sqla (required for dashboard time filters)
Auto-sync — datasource_access permissions are automatically synchronized when dashboard roles change

Architecture

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 Compatibility

Tested with: Apache Superset 6.0.1
Authentication: JWT (recommended) — API Key (sst_*) is not implemented in Superset
Required Superset user: Admin role (for full API access)

Recommended Superset Configuration

Add to your 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

Development

Setup

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

Running Locally

# Run from source
uv run python -m mcp_superset

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

Running Tests

uv run python test_all_tools.py

Known Superset API Quirks

These are handled automatically by the MCP server, but useful to know when debugging:

Quirk	Details
RISON pagination	Superset ignores `page`/`page_size` as query params; must use RISON in `q` parameter
CSRF required	All POST/PUT/DELETE need `X-CSRFToken` header + session cookie
Referer required	SQL Lab returns 403 without `Referer` header
Tag API returns `{}`	Tag creation doesn't return the ID; must query list
Tag update needs `name`	Field is mandatory even if unchanged
Role permissions replace	`POST /security/roles/{id}/permissions` replaces ALL permissions
RLS update replaces	`PUT /rowlevelsecurity/{id}` replaces ALL provided fields
Dataset update columns	`PUT /dataset/{id}` with `columns` replaces ALL columns
Dashboard copy	Requires `json_metadata` (can be `"{}"`)
Native filter IDs	Must be `NATIVE_FILTER-<uuid>` format
`filter_time` needs `granularity_sqla`	Charts without it silently ignore time filters
Number formatting	`SMART_NUMBER` abbreviates; use `,d` or `,.2f` for exact

License

MIT — Stanislav Chernov (@bintocher)

Как установить

Добавь это в claude_desktop_config.json и перезапусти Claude Desktop.

{
  "mcpServers": {
    "bintocher-mcp-superset": {
      "command": "npx",
      "args": []
    }
  }
}