|
| 1 | +--- |
| 2 | +title: Using AI with Superset |
| 3 | +hide_title: true |
| 4 | +sidebar_position: 5 |
| 5 | +version: 1 |
| 6 | +--- |
| 7 | + |
| 8 | +<!-- |
| 9 | +Licensed to the Apache Software Foundation (ASF) under one |
| 10 | +or more contributor license agreements. See the NOTICE file |
| 11 | +distributed with this work for additional information |
| 12 | +regarding copyright ownership. The ASF licenses this file |
| 13 | +to you under the Apache License, Version 2.0 (the |
| 14 | +"License"); you may not use this file except in compliance |
| 15 | +with the License. You may obtain a copy of the License at |
| 16 | + |
| 17 | + http://www.apache.org/licenses/LICENSE-2.0 |
| 18 | + |
| 19 | +Unless required by applicable law or agreed to in writing, |
| 20 | +software distributed under the License is distributed on an |
| 21 | +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 22 | +KIND, either express or implied. See the License for the |
| 23 | +specific language governing permissions and limitations |
| 24 | +under the License. |
| 25 | +--> |
| 26 | + |
| 27 | +# Using AI with Superset |
| 28 | + |
| 29 | +Superset supports AI assistants through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Connect Claude, ChatGPT, or other MCP-compatible clients to explore your data, build charts, create dashboards, and run SQL -- all through natural language. |
| 30 | + |
| 31 | +:::info |
| 32 | +Requires Superset 5.0+. Your admin must enable and deploy the MCP server before you can connect. |
| 33 | +See the **[MCP Server admin guide](/admin-docs/configuration/mcp-server)** for setup instructions. |
| 34 | +::: |
| 35 | + |
| 36 | +--- |
| 37 | + |
| 38 | +## What Can AI Do with Superset? |
| 39 | + |
| 40 | +### Explore Your Data |
| 41 | + |
| 42 | +Ask your AI assistant to browse what's available in your Superset instance: |
| 43 | + |
| 44 | +- **List datasets** -- see all datasets you have access to, with filtering and search |
| 45 | +- **Get dataset details** -- column names, types, available metrics, and filters |
| 46 | +- **List charts and dashboards** -- find existing visualizations by name or keyword |
| 47 | +- **Get chart and dashboard details** -- understand what a chart shows, its query, and configuration |
| 48 | + |
| 49 | +**Example prompts:** |
| 50 | +> "What datasets are available?" |
| 51 | +> "Show me the columns in the sales_orders dataset" |
| 52 | +> "Find dashboards related to revenue" |
| 53 | +
|
| 54 | +### Build Charts |
| 55 | + |
| 56 | +Describe the visualization you want and AI creates it for you: |
| 57 | + |
| 58 | +- **Create charts from natural language** -- describe what you want to see and AI picks the right chart type, metrics, and dimensions |
| 59 | +- **Preview before saving** -- AI generates a preview so you can review before committing |
| 60 | +- **Modify existing charts** -- update filters, change chart types, add metrics |
| 61 | +- **Get Explore links** -- open any chart in Superset's Explore view for further refinement |
| 62 | + |
| 63 | +**Example prompts:** |
| 64 | +> "Create a bar chart showing monthly revenue by region from the sales dataset" |
| 65 | +> "Update chart 42 to use a line chart instead" |
| 66 | +> "Give me a link to explore this chart further" |
| 67 | +
|
| 68 | +### Create Dashboards |
| 69 | + |
| 70 | +Build dashboards from a collection of charts: |
| 71 | + |
| 72 | +- **Generate dashboards** -- create a new dashboard with a set of charts, automatically laid out |
| 73 | +- **Add charts to existing dashboards** -- place a chart on an existing dashboard with automatic positioning |
| 74 | + |
| 75 | +**Example prompts:** |
| 76 | +> "Create a dashboard called 'Q4 Sales Overview' with charts 10, 15, and 22" |
| 77 | +> "Add the revenue trend chart to the executive dashboard" |
| 78 | +
|
| 79 | +### Run SQL Queries |
| 80 | + |
| 81 | +Execute SQL directly through your AI assistant: |
| 82 | + |
| 83 | +- **Run queries** -- execute SQL with full Superset RBAC enforcement (you can only query data your roles allow) |
| 84 | +- **Open SQL Lab** -- get a link to SQL Lab pre-populated with a query, ready to run and explore |
| 85 | + |
| 86 | +**Example prompts:** |
| 87 | +> "Run this query: SELECT region, SUM(revenue) FROM sales GROUP BY region" |
| 88 | +> "Open SQL Lab with a query to show the top 10 customers by order count" |
| 89 | +
|
| 90 | +### Analyze Chart Data |
| 91 | + |
| 92 | +Pull the raw data behind any chart: |
| 93 | + |
| 94 | +- **Get chart data** -- retrieve the data a chart displays, with support for JSON, CSV, and Excel export formats |
| 95 | +- **Inspect results** -- useful for verifying what a visualization shows or feeding data into other tools |
| 96 | + |
| 97 | +**Example prompts:** |
| 98 | +> "Get the data behind chart 42" |
| 99 | +> "Export chart 15 data as CSV" |
| 100 | +
|
| 101 | +### Check Instance Status |
| 102 | + |
| 103 | +- **Health check** -- verify your Superset instance is up and the MCP connection is working |
| 104 | +- **Instance info** -- get high-level statistics about your Superset instance (number of datasets, charts, dashboards) |
| 105 | + |
| 106 | +**Example prompts:** |
| 107 | +> "Is Superset healthy?" |
| 108 | +> "How many dashboards are in this instance?" |
| 109 | +
|
| 110 | +--- |
| 111 | + |
| 112 | +## Connecting Your AI Client |
| 113 | + |
| 114 | +Once your admin has deployed the MCP server, connect your AI client using the instructions below. |
| 115 | + |
| 116 | +### Claude Desktop |
| 117 | + |
| 118 | +Edit your Claude Desktop config file: |
| 119 | + |
| 120 | +- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` |
| 121 | +- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` |
| 122 | +- **Linux**: `~/.config/Claude/claude_desktop_config.json` |
| 123 | + |
| 124 | +```json |
| 125 | +{ |
| 126 | + "mcpServers": { |
| 127 | + "superset": { |
| 128 | + "url": "http://localhost:5008/mcp" |
| 129 | + } |
| 130 | + } |
| 131 | +} |
| 132 | +``` |
| 133 | + |
| 134 | +Restart Claude Desktop. The hammer icon in the chat bar confirms the connection. |
| 135 | + |
| 136 | +If your admin has enabled JWT authentication, you may need to include a token: |
| 137 | + |
| 138 | +```json |
| 139 | +{ |
| 140 | + "mcpServers": { |
| 141 | + "superset": { |
| 142 | + "command": "npx", |
| 143 | + "args": [ |
| 144 | + "-y", |
| 145 | + "mcp-remote@latest", |
| 146 | + "http://your-superset-host:5008/mcp", |
| 147 | + "--header", |
| 148 | + "Authorization: Bearer YOUR_TOKEN" |
| 149 | + ] |
| 150 | + } |
| 151 | + } |
| 152 | +} |
| 153 | +``` |
| 154 | + |
| 155 | +### Claude Code (CLI) |
| 156 | + |
| 157 | +Add to your project's `.mcp.json`: |
| 158 | + |
| 159 | +```json |
| 160 | +{ |
| 161 | + "mcpServers": { |
| 162 | + "superset": { |
| 163 | + "type": "url", |
| 164 | + "url": "http://localhost:5008/mcp" |
| 165 | + } |
| 166 | + } |
| 167 | +} |
| 168 | +``` |
| 169 | + |
| 170 | +### ChatGPT |
| 171 | + |
| 172 | +1. Click your profile icon > **Settings** > **Apps and Connectors** |
| 173 | +2. Enable **Developer Mode** in Advanced Settings |
| 174 | +3. In the chat composer, press **+** > **Add sources** > **App** > **Connect more** > **Create app** |
| 175 | +4. Enter a name and your MCP server URL |
| 176 | +5. Click **I understand and continue** |
| 177 | + |
| 178 | +:::info |
| 179 | +ChatGPT MCP connectors require a Pro, Team, Enterprise, or Edu plan. |
| 180 | +::: |
| 181 | + |
| 182 | +Ask your admin for the MCP server URL and any authentication tokens you need. |
| 183 | + |
| 184 | +--- |
| 185 | + |
| 186 | +## Tips for Best Results |
| 187 | + |
| 188 | +- **Be specific** -- "Create a bar chart of monthly revenue by region from the sales dataset" works better than "Make me a chart" |
| 189 | +- **Start with exploration** -- ask what datasets and charts exist before creating new ones |
| 190 | +- **Review AI-generated content** -- always check chart configurations and SQL before saving or sharing |
| 191 | +- **Use Explore for refinement** -- ask AI for an Explore link, then fine-tune interactively in the Superset UI |
| 192 | +- **Check permissions if you get errors** -- AI respects Superset's RBAC, so you can only access data your roles allow |
| 193 | + |
| 194 | +--- |
| 195 | + |
| 196 | +## Available Tools Reference |
| 197 | + |
| 198 | +| Tool | Description | |
| 199 | +|------|-------------| |
| 200 | +| `health_check` | Verify the MCP server is running and connected | |
| 201 | +| `get_instance_info` | Get instance statistics (dataset, chart, dashboard counts) | |
| 202 | +| `get_schema` | Discover available charts, datasets, and dashboards with schema info | |
| 203 | +| `list_datasets` | List datasets with filtering and search | |
| 204 | +| `get_dataset_info` | Get dataset metadata (columns, metrics, filters) | |
| 205 | +| `list_charts` | List charts with filtering and search | |
| 206 | +| `get_chart_info` | Get chart metadata and configuration | |
| 207 | +| `get_chart_data` | Retrieve chart data (JSON, CSV, or Excel) | |
| 208 | +| `get_chart_preview` | Generate a chart preview (URL, ASCII, table, or Vega-Lite) | |
| 209 | +| `generate_chart` | Create a new chart from a specification | |
| 210 | +| `update_chart` | Modify an existing chart's configuration | |
| 211 | +| `update_chart_preview` | Update a cached chart preview without saving | |
| 212 | +| `list_dashboards` | List dashboards with filtering and search | |
| 213 | +| `get_dashboard_info` | Get dashboard metadata and layout | |
| 214 | +| `generate_dashboard` | Create a new dashboard with specified charts | |
| 215 | +| `add_chart_to_existing_dashboard` | Add a chart to an existing dashboard | |
| 216 | +| `execute_sql` | Run a SQL query with RBAC enforcement | |
| 217 | +| `open_sql_lab_with_context` | Open SQL Lab with a pre-populated query | |
| 218 | +| `generate_explore_link` | Generate an Explore URL for interactive visualization | |
| 219 | + |
| 220 | +--- |
| 221 | + |
| 222 | +## Troubleshooting |
| 223 | + |
| 224 | +### "Connection refused" or "Cannot connect" |
| 225 | + |
| 226 | +- Confirm the MCP server URL with your admin |
| 227 | +- For Claude Desktop: fully quit the app (not just close the window) and restart after config changes |
| 228 | +- Check that the URL path ends with `/mcp` (e.g., `http://localhost:5008/mcp`) |
| 229 | + |
| 230 | +### "Permission denied" or missing data |
| 231 | + |
| 232 | +- Superset's RBAC controls what you can access through AI, just like in the Superset UI |
| 233 | +- Ask your admin to verify your roles and permissions |
| 234 | +- Try accessing the same data through the Superset web UI to confirm your access |
| 235 | + |
| 236 | +### "Response too large" |
| 237 | + |
| 238 | +- Ask for smaller result sets: use filters, reduce `page_size`, or request specific columns |
| 239 | +- Example: "Show me the top 10 rows from the sales dataset" instead of "Show me all sales data" |
| 240 | + |
| 241 | +### AI doesn't see Superset tools |
| 242 | + |
| 243 | +- Verify the connection in your AI client (e.g., the hammer icon in Claude Desktop) |
| 244 | +- Ask the AI "What Superset tools are available?" to confirm the connection |
| 245 | +- Restart your AI client if you recently changed the configuration |
0 commit comments