Superset MCP Server

Local stdio MCP server for reviewing Apache Superset dashboards, retrieving chart data, executing SQL through SQL Lab, and creating or updating saved queries.

The server only calls Superset's public REST API. It does not connect directly to an analytical database. No delete, dashboard mutation, chart mutation, dataset mutation, database-administration, screenshot, or generic arbitrary-request tools are exposed.

Superset's built-in MCP server

Superset 5.0+ also includes an official MCP service that an administrator can run alongside the Superset deployment:

superset mcp run --host 127.0.0.1 --port 5008

That service is the preferred option when your Superset version includes it and you have deployment access. It provides native RBAC enforcement, audit logging, chart/dashboard creation, SQL execution, and saved-query creation at an HTTP /mcp endpoint. See the official MCP deployment guide and available tools.

This repository remains useful when:

• the Superset administrator has not deployed the built-in MCP process;
• only the public REST URL and a normal Superset login are available;
• a local stdio MCP server is required; or
• saved-query inspection and update support are needed in addition to the built-in server's documented save_sql_query creation tool.

Do not deploy both integrations under the same MCP server name without intentionally choosing which one future projects should use.

Requirements

• Python 3.11 or newer (Python 3.13 is supported by this project)
• Network access from this machine to your Superset URL
• A dedicated Superset account with only the roles and database permissions the MCP server needs

execute_sql deliberately passes SQL through unchanged. Superset's database configuration and the underlying database user are therefore the security boundary for DML, DDL, CTAS, and other statements. Use a least-privilege account.

Windows setup

Run these commands from super_set_mcp in PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
Copy-Item .env.example .env

Edit .env with the real connection values. Do not commit .env.

SUPERSET_URL=https://superset.example.com
SUPERSET_USERNAME=mcp-service-user
SUPERSET_PASSWORD=replace-me
SUPERSET_PROVIDER=db
SUPERSET_VERIFY_SSL=true

The URL must be the Superset base URL without /api/v1. SUPERSET_PROVIDER can be changed to ldap when that is how the Superset login endpoint is configured.

Run and validate

Run the server over stdio:

.\.venv\Scripts\python.exe -m superset_mcp.server

The process waits silently for MCP protocol messages; that is normal for a stdio server. Before using any data or write tool, call superset_status. It checks login and current-user access and, by default, probes Superset's OpenAPI endpoint.

Run the mocked test suite without contacting Superset:

.\.venv\Scripts\python.exe -m pytest

MCP client configuration

Use an absolute path so future projects can launch the same server regardless of their working directory:

{
  "mcpServers": {
    "superset": {
      "command": "C:\\path\\to\\super_set_mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "superset_mcp.server"],
      "cwd": "C:\\path\\to\\super_set_mcp"
    }
  }
}

Keeping cwd set to this folder allows pydantic-settings to load its local .env. If a client supports an env map, secrets may instead be injected by the client or a secret manager; do not place real credentials in shared project configuration.

Tools

Tool	Purpose
superset_status	Validate settings, JWT login, current user, and optional OpenAPI availability
list_dashboards	Search and paginate dashboards
get_dashboard	Read dashboard metadata by ID or slug
get_dashboard_charts	Read a dashboard's chart definitions and form data
get_dashboard_datasets	Read datasets used by a dashboard
get_chart	Read chart metadata
get_chart_data	Retrieve data for a saved chart query
list_databases	Find accessible database IDs for SQL Lab and saved queries
execute_sql	Execute SQL unchanged through SQL Lab
get_query	Inspect query history or asynchronous status
get_sql_result	Retrieve asynchronous results using resultsKey
list_saved_queries	Search and paginate saved queries
get_saved_query	Read one saved query
create_saved_query	Preview/create a saved query; requires confirm=true to write
update_saved_query	Preview/update while preserving unspecified fields; requires confirm=true to write

There is no saved-query delete tool.

Recommended first-use sequence

1. Configure the real URL and credentials locally.
2. Call superset_status.
3. Call list_databases, list_dashboards, and list_saved_queries to validate read permissions.
4. Review a dashboard through get_dashboard, get_dashboard_charts, and get_dashboard_datasets.
5. Retrieve chart data only when needed; force=true bypasses Superset's cache and may increase database load.
6. Execute SQL only after verifying the selected database ID and role. Long-running deployments can use run_async=true, then get_query/get_sql_result.
7. Call create/update first with the default confirm=false, inspect the preview, and call again with confirm=true only when the payload is correct.

Troubleshooting

• configured: false: one or more required SUPERSET_* settings are missing or the URL is invalid.
• HTTP 401: check username, password, provider, and whether REST login is enabled.
• HTTP 403: the Superset role lacks access to the dashboard, chart, database, SQL Lab, or saved-query resource.
• TLS/transport error: keep SUPERSET_VERIFY_SSL=true and install/configure the organization's trusted CA. Disable verification only for a controlled temporary diagnostic.
• OpenAPI unavailable: the deployment may not expose /api/v1/_openapi; normal tools can still work. Superset's Swagger UI may also require FAB_API_SWAGGER_UI = True.
• Result expired (HTTP 410): rerun the asynchronous query because its result key is no longer retained by Superset.
• Response too large: increase SUPERSET_MAX_RESPONSE_BYTES cautiously or reduce query/page limits.

Security behavior

• Passwords and JWTs remain in environment configuration and process memory; they are never returned by tools.
• On HTTP 401, the client tries the refresh token and then performs one fresh login if refresh fails.
• API error output includes method, public API path, status, and safe error fields, but excludes request headers and credentials.
• Page sizes, query limits, request timeouts, and response bytes are bounded by environment settings.
• Saved-query updates fetch the existing record and preserve fields not supplied by the caller.
• Optional update fields set to null are treated as omitted by the MCP tool. This version does not expose field-clearing semantics.

API references

• Superset API reference
• Security and JWT endpoints
• Dashboards
• Charts
• Queries and saved queries
• SQL Lab
• MCP Python SDK