Which integrations are available for this server?

Provides comprehensive control over Apache Superset instances, including tools for managing dashboards, charts, datasets, SQL Lab, security roles, and Row Level Security (RLS).

mcp-superset

PyPI version PyPI downloads Python 3.12+ License: MIT CodeQL

Superset 6.0.1 MCP Typed Ruff Tools: 128+ 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 128+ tools.

Comparison with Other Superset MCP Servers

Feature	mcp-superset	superset-mcp	superset-mcp (Winding2020)	superset-mcp-server
Total tools	128+	~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)	22 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

128+ 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 (128+)

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 (22 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_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_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

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 tools (22)
        ├── 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)