MCP Superset

mcp-superset

[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

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 PyPIpip 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:

# RequiredSUPERSET_BASE_URL=https://superset.example.comSUPERSET_USERNAME=adminSUPERSET_PASSWORD=your_password
# OptionalSUPERSET_AUTH_PROVIDER=db          # db (default) or ldapSUPERSET_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)

When Superset is behind SSO (OAuth/OIDC/SAML), password login via the REST API is unavailable. Instead, supply a browser session cookie:

Copy the cookie from your browser's dev tools (Application → Cookies → your Superset domain → session). The MCP server sends it on every request and fetches CSRF tokens with it. The session cannot be renewed server-side, so when it expires you must paste a fresh value and restart the server.

Two things worth checking before you use this mode:

• The cookie name is not always session. Instances that set SESSION_COOKIE_NAME in superset_config.py use a different name (s, for example). Use the name shown in dev tools and set SUPERSET_SESSION_COOKIE_NAME accordingly.
• The instance must accept session authentication on /api/v1/. Where the REST API is configured for JWT only, requests carrying a valid session cookie still return 401 {"msg": "Missing Authorization Header"} - refreshing the cookie will not help, and JWT mode is the only option there.

Treat the cookie as a credential: it grants full access to your Superset account for the lifetime of the session. Keep it in .env (which is gitignored), not in shell history or committed config.

Running

# Using CLI (after pip install)mcp-superset
# Run without installinguvx mcp-superset
# Using Python modulepython -m mcp_superset
# With uv from sourceuv run mcp-superset
# With custom settingsmcp-superset --host 0.0.0.0 --port 9000 --transport sse
# With custom .env filemcp-superset --env-file /path/to/.env
# Using stdio transport (for Claude Desktop, Cursor, etc.)mcp-superset --transport stdio

CLI Options

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)

Dashboard Filters (5 tools)

Charts (11 tools)

Databases (18 tools)

Datasets (11 tools)

SQL Lab & Queries (13 tools)

Security & Access Control (26 tools)

Groups (9 tools)

Tags (7 tools)

System & Reports (21 tools)

Audit (1 tool)

Safety Features

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

Confirmation Flags

Destructive operations require explicit confirmation parameters:

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 sizeFAB_API_MAX_PAGE_SIZE = 100

Development

Setup

git clone https://github.com/bintocher/mcp-superset.gitcd superset-mcp
# Create virtual environment and install in editable modeuv venvuv pip install -e ".[dev]"
# Copy and configure .envcp .env.example .env# Edit .env with your Superset credentials

Running Locally

# Run from sourceuv run python -m mcp_superset
# Or with CLIuv 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:

License

MIT — Stanislav Chernov (@bintocher)