Provides tools for interacting with Apache Superset, enabling management of BI assets such as dashboards, charts, datasets, and databases, with read-only access by default and optional write capabilities.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@superset compare production dashboards with git"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Production-grade management of Apache Superset 6.1.0 where Git is the source of truth for BI metadata, the Superset metadata database is treated as runtime state, and Claude Code can drive Superset through the official MCP service without bypassing review.
Claude Code ──MCP──► Superset MCP service (read-only by default)
│
▼
Superset API ──► Superset UI
│
▼
Superset metadata DB ◄── runtime state, NOT the truth
▲
│ export / import
▼
Git repository ◄── the source of truth
│
validate · unit · integration · API · E2E · drift
│
DEV → STAGING → PRODRelated MCP server: superset-mcp
Requirement | Version used | Notes |
Docker + Compose | 29.7.2 / v5.4.0 | runs Superset, Postgres and Redis |
Python | 3.12 | repo tooling only; Superset runs in Docker |
Node.js | 20+ | Playwright E2E |
Apache Superset | 6.1.0 | pinned via |
The image is built from apache/superset:6.1.0-py311. The -py311 variant is
required: the default 6.1.0 tag ships Python 3.10 and the MCP service needs
fastmcp>=3.1.0, which requires Python 3.11+.
# 1. Secrets. .env is gitignored and must never be committed.
cp .env.example .env
./scripts/gen_secrets.sh >> .env # appends freshly generated values
$EDITOR .env # remove the CHANGE_ME placeholder lines
# 2. Repo tooling
python3.12 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt
npm install && npx playwright install chromium
# 3. Start Superset, the warehouse, Redis and the MCP service
docker compose -f docker/docker-compose.yml --env-file .env up -d --build
# 4. Deploy the version-controlled assets
set -a; source .env; set +a
.venv/bin/python scripts/import.py --env dev
# 5. Confirm it works
.venv/bin/python scripts/smoke_test.py --env devSuperset is then at http://localhost:8088 and the MCP service at http://localhost:5008/mcp.
The compose file refuses to start without SUPERSET_SECRET_KEY,
METADATA_DB_PASSWORD, WAREHOUSE_DB_PASSWORD and SUPERSET_ADMIN_PASSWORD.
That is deliberate: there is no insecure default to accidentally ship.
Superset → export → normalize → git diff → commit → pull requestscripts/export.sh --env dev
git diff assets/ # review the semantic changeExport is deterministic: running it twice against an unchanged Superset produces byte-identical files. Numeric primary keys, export timestamps, credentials and derived query caches are all removed or rewritten - see docs/gitops.md for every rule and why it exists.
git checkout → validate → resolve placeholders → import → smoke testscripts/validate.py # offline, no Superset needed
scripts/import.sh --env dev --dry-run # resolve without deploying
scripts/import.sh --env dev
scripts/smoke_test.py --env devImports are idempotent - identity is the asset UUID, so deploying twice updates rather than duplicates.
Task | Command |
Start the stack |
|
Stop |
|
Reset completely |
|
Export Superset → Git |
|
Verify Git matches Superset |
|
Import Git → Superset |
|
Preview an import |
|
Validate assets (offline) |
|
Detect drift |
|
Smoke test |
|
Deployment history |
|
Roll back |
|
Seed a fresh DEV instance |
|
Scripts read credentials from the environment. Locally, scripts/*.sh source
.env for you; when calling the Python entry points directly, run
set -a; source .env; set +a first.
The project ships .mcp.json, so Claude Code discovers the server on its own:
{ "mcpServers": { "superset": { "type": "http", "url": "http://localhost:5008/mcp" } } }claude mcp list # superset: http://localhost:5008/mcp (HTTP) - ✔ ConnectedProject-scoped servers require a one-time approval prompt the first time you
start claude in this directory.
MCP is read-only unless explicitly enabled. The code default is read-only,
so an unset variable is always safe. DEV ships with writes enabled
(.env.example) because the governed workflow modifies DEV and then exports;
STAGING and PROD are read-only, and production additionally requires
MCP_ALLOW_PROD_WRITES=true or Superset refuses to start.
Superset tags every mutating MCP tool mutate, and docker/mcp_server.py
disables that tag, so the write tools are not merely refused - they are never
registered:
| Tools exposed | Mutating tools |
| 16 | none; |
| 24 | all 8 exposed |
Read docs/mcp.md before enabling writes anywhere.
.venv/bin/python -m pytest tests/unit -q # 135 tests, no services needed
.venv/bin/python -m pytest tests/api -q # 42 tests, needs Superset + MCP
.venv/bin/python -m pytest tests/integration -q # 12 tests, needs Superset
npx playwright test # 27 browser tests (Chromium)
npx playwright test --headed # watch them run
npm run test:e2e:update-snapshots # regenerate visual baselinesSuite | Count | What it protects |
unit | 135 | normalization determinism, naming rules, secret detection, manifest generation, asset integrity |
API | 42 | auth, assets, SQL, import/export, MCP read-only enforcement |
integration | 12 | dependency chain, idempotency, |
E2E | 27 | login, rendering, filters, navigation, visual regression |
See docs/testing.md.
main → deploy-dev (automatic) → deploy-staging (on DEV success) → deploy-prod (manual approval)Production additionally: refuses to deploy over unreviewed drift, backs up the current state first, and rolls itself back automatically if verification fails. See docs/deployment.md.
assets/ version-controlled BI assets (the source of truth)
databases/ datasets/ charts/ dashboards/ queries/ tags/
config/ superset_config.py + per-environment settings (no secrets)
docker/ Dockerfile, compose stack, MCP entrypoint
scripts/ export, import, validate, diff, smoke test, rollback
lib/ normalization engine, REST/MCP clients, conventions
sql/ warehouse model, metric definitions, validation queries
tests/ unit, api, integration, e2e
docs/ architecture and standards
.github/workflows CI and the promotion pipelineDocument | Contents |
rules for AI agents working in this repository | |
components, data flow, design decisions | |
export, import, normalization, drift, rollback | |
MCP architecture, auth, the read-only model | |
the test strategy and how to extend it | |
promotion, rollback, production checklist | |
enforced naming rules | |
dashboard requirements | |
chart requirements | |
metric definitions | |
database and dataset rules |
See docs/deployment.md for the full list with reasoning. In brief:
Not verified: GitHub Actions workflows have not executed on GitHub (no remote is configured); STAGING and PROD environments do not exist here, so only DEV has been exercised end to end.
MCP JWT authentication is implemented and configured but has been tested only
in MCP_AUTH_ENABLED=false dev mode; no identity provider was available.
Vault / AWS / GCP / Azure secret backends are designed for (the env:
indirection seam) but only environment variables are implemented.
Superset's DBEventLogger raises a TypeError when the MCP middleware logs a
tool error; MCP auditing therefore relies on the middleware's structured
stdout log. See docs/mcp.md.
This server cannot be deployed
Let AI agents query data and act across all your business apps via MCP.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Governed BI MCP. Ask questions of live company data and list workspace sources via OAuth.
