chrissmartin/apache-superset-mcp

Apache Superset MCP Server

A generalized Model Context Protocol (MCP) server that connects Apache Superset to AI assistants and other MCP-compatible applications. Works with Claude Desktop, VS Code, Continue.dev, Cline, and any MCP client.

📁 Repository: https://github.com/chrissmartin/apache-superset-mcp

🚀 Quick Start

One-Command Install (Recommended)

# Install from PyPI
pip install apache-superset-mcp

# Interactive setup wizard
apache-superset-mcp setup

# Start the server
apache-superset-mcp server

Developer Install

# 1. Clone and install dependencies
git clone https://github.com/chrissmartin/apache-superset-mcp.git
cd superset-mcp
uv sync

# 2. Setup authentication
python main.py --setup

# 3. Test the server
python main.py --test

# 4. Start MCP server
python main.py

📋 Features

• 15 MCP Tools for complete Superset management
• Multiple Client Support - Claude Desktop, VS Code, Continue.dev, Cline, and more
• Three Authentication Methods - Cookies, password, OAuth
• One-Command Installation - pip install apache-superset-mcp
• Interactive Setup Wizard with auto-client detection
• Automated CI/CD Pipeline with semantic versioning
• Type-Safe Operations with Pydantic models
• Comprehensive Error Handling and validation
• Multiple Deployment Options - PyPI, Docker, standalone executables
• REST API Alternative for direct HTTP access

🏗️ Project Structure

superset-mcp/
├── main.py                    # Main entry point with CLI
├── src/
│   ├── mcp_server.py         # MCP protocol server
│   ├── rest_server.py        # REST API server (alternative)
│   └── superset_client.py    # Superset API client
├── scripts/
│   ├── extract_tokens.py     # Authentication setup wizard
│   ├── examples.py          # Interactive examples
│   ├── start_mcp_server.py  # Advanced server startup
│   └── test_mcp_server.py   # Test suite
├── config/
│   ├── claude_desktop.json  # Claude Desktop configuration
│   ├── vscode_settings.json # VS Code MCP settings
│   ├── continue_config.json # Continue.dev configuration
│   ├── cline_config.json    # Cline configuration
│   └── generic_mcp.json     # Template for other clients

## 🤝 Contributing

We welcome contributions! This project uses modern Python tooling for code quality:

```bash
# Quick development setup
make dev-setup

# Code quality checks
make lint          # Check code
make format        # Fix formatting
make test          # Run tests
make quick-check   # All checks

See for detailed guidelines.

📁 Documentation

├── docs/
│   ├── CLIENT_EXAMPLES.md       # Client-specific examples
│   ├── CONTRIBUTING.md          # Development guidelines
│   └── STREAMLINED_SETUP.md     # Advanced installation options
├── .env.example                 # Environment template
└── pyproject.toml               # Dependencies

🔧 Installation

Option 1: PyPI Package (Recommended)

# One-command install
pip install apache-superset-mcp

# Verify installation
apache-superset-mcp version

Option 2: Docker

# Run with Docker
docker run -p 8000:8000 \
  -e SUPERSET_HOST=https://your-superset.com \
  -e SUPERSET_SESSION_COOKIE=your_cookie \
  apache-superset-mcp:latest

Option 3: Developer Install

Prerequisites:

• Python 3.13+
• uv package manager
• Access to Apache Superset instance

git clone https://github.com/chrissmartin/apache-superset-mcp.git
cd superset-mcp
uv sync

Verify Installation:

python main.py --status

See for more installation options including Docker, auto-installers, and platform-specific packages.

🔐 Authentication Setup

Quick Setup (Recommended)

PyPI Package

apache-superset-mcp setup

Developer Install

python main.py --setup

Follow the interactive wizard to extract authentication tokens from your browser.

Manual Setup

Create a .env file with your Superset credentials:

# Required
SUPERSET_HOST=https://your-superset-instance.com
SUPERSET_AUTH_METHOD=cookies

# Cookie Authentication (Recommended)
SUPERSET_SESSION_COOKIE=.eJyNkVtz2jAQhf9Kx89JsGTrxhsNY5sEQsChNe1kPJI8sl0...
SUPERSET_CSRF_TOKEN=ImRlZGM3NDgxOTYxNjFhOTgyMDcxYjg2NDVmYTYxODk3OGI0N2YxOTgi...

# Alternative: Password Authentication
# SUPERSET_AUTH_METHOD=password
# SUPERSET_USERNAME=your_username
# SUPERSET_PASSWORD=your_password

# Alternative: OAuth Authentication
# SUPERSET_AUTH_METHOD=oauth
# SUPERSET_OAUTH_TOKEN=your_oauth_token

🎯 Client Setup

Claude Desktop

1. Copy configuration:

   cp config/claude_desktop.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

2. Update paths and credentials in the configuration file

3. Restart Claude Desktop

VS Code

1. Install MCP extension for VS Code

2. Add MCP server configuration to your VS Code settings. Choose one method:

   Option A: Copy template to workspace

   mkdir -p .vscode
   cp config/vscode_settings.json .vscode/settings.json
   

   Option B: Add to user/workspace settings

   Open VS Code settings (Cmd/Ctrl + ,), click "Open Settings (JSON)", and add:

   {
     "mcp.servers": {
       "superset": {
         "command": "python",
         "args": ["main.py"],
         "cwd": "/path/to/superset-mcp",
         "env": {
           "PYTHONPATH": "/path/to/superset-mcp",
           "SUPERSET_HOST": "https://your-superset-instance.com",
           "SUPERSET_AUTH_METHOD": "cookies",
           "SUPERSET_SESSION_COOKIE": "your_session_cookie_here",
           "SUPERSET_CSRF_TOKEN": "your_csrf_token_here"
         }
       }
     }
   }
   

3. Update the configuration with your actual credentials:

   • Replace /path/to/superset-mcp with the full path to this project
   • Replace your-superset-instance.com with your Superset URL
   • Replace authentication tokens with your actual values

   Alternative authentication methods:

   // Password authentication
   "env": {
     "SUPERSET_HOST": "https://your-superset-instance.com",
     "SUPERSET_AUTH_METHOD": "password",
     "SUPERSET_USERNAME": "your_username",
     "SUPERSET_PASSWORD": "your_password"
   }
   
   // OAuth authentication
   "env": {
     "SUPERSET_HOST": "https://your-superset-instance.com",
     "SUPERSET_AUTH_METHOD": "oauth",
     "SUPERSET_OAUTH_TOKEN": "your_oauth_token"
   }
   

4. Reload VS Code window

Continue.dev

1. Copy configuration:

   cp config/continue_config.json ~/.continue/config.json
   

2. Update paths and credentials

3. Restart Continue

Cline

1. Install Cline extension in VS Code

2. Configure MCP servers using config/cline_config.json

3. Restart VS Code

Other MCP Clients

Use config/generic_mcp.json as a template for other MCP-compatible applications.

🛠️ Available Tools

💬 Usage Examples

Basic Operations

List Resources:

You: "Show me all my Superset dashboards"
AI: [Lists all dashboards with IDs, names, and status]

Create Charts:

You: "Create a line chart showing sales trends from dataset 5"
AI: [Creates chart with appropriate configuration]

Dashboard Management:

You: "Create a complete analytics dashboard for Q1 sales data"
AI: [Creates dataset, multiple charts, and organizes in dashboard]

Advanced Workflows

Data Exploration:

You: "What data sources are available? Create some exploratory visualizations."
AI: [Surveys databases/datasets, creates sample charts]

Resource Cleanup:

You: "Find and remove any test resources I created this week"
AI: [Identifies test resources, confirms before deletion]

See for detailed client-specific examples.

🧪 Testing

Run Test Suite

PyPI Package

apache-superset-mcp test

Developer Install

python main.py --test

This will:

• ✅ Check dependencies and configuration
• ✅ Test Superset connection
• ✅ Validate all MCP tools
• ✅ Run sample operations
• ✅ Test error handling

Interactive Examples

python scripts/examples.py

Provides:

• Full workflow demonstrations
• Interactive chart creator
• Resource listing and management
• Cleanup utilities

Manual Testing

Start the server and test with your AI client:

PyPI Package

apache-superset-mcp server

Developer Install

python main.py

Then in your AI client, try:

• "Show me all dashboards in Superset"
• "Create a test chart"
• "Test the Superset connection"

🔄 Alternative: REST API

Start the REST API server instead of MCP:

PyPI Package

apache-superset-mcp --rest

Developer Install

python main.py --rest

• API docs: http://localhost:8000/docs
• Interactive API: http://localhost:8000/redoc

🐛 Troubleshooting

Common Issues

Authentication Failed:

apache-superset-mcp setup      # PyPI package
python main.py --setup         # Developer install

Connection Timeout:

• Check SUPERSET_HOST URL
• Verify network connectivity
• Confirm Superset is running

Import Errors:

uv sync  # Reinstall dependencies

MCP Client Issues:

• Check file paths in configuration
• Verify server is running: apache-superset-mcp test or python main.py --test
• Restart your MCP client

Debug Mode

export DEBUG=true
export LOG_LEVEL=debug
apache-superset-mcp server     # PyPI package
python main.py                 # Developer install

Get Help

1. Check status: apache-superset-mcp status or python main.py --status
2. Run tests: apache-superset-mcp test or python main.py --test
3. Check logs: Look for error messages in terminal
4. Documentation: See docs/ folder for detailed guides

📖 Documentation

• - Usage examples for different AI clients
• - Advanced installation options and automation
• - Development guidelines and setup
• - Automated release process with semantic versioning
• Configuration Templates - Ready-to-use configs in config/ folder

Online Resources:

• 📚 Full Documentation
• 🐛 Issue Tracker
• 🚀 Releases
• 💬 Discussions
• 🔄 CI/CD Pipeline

🎛️ CLI Commands

PyPI Package Commands

apache-superset-mcp setup          # Interactive setup wizard
apache-superset-mcp server         # Start MCP server (default)
apache-superset-mcp test           # Test Superset connection
apache-superset-mcp status         # Show configuration status
apache-superset-mcp version        # Show version info
apache-superset-mcp --help         # Show all options

Developer Install Commands

python main.py              # Start MCP server (default)
python main.py --rest       # Start REST API server
python main.py --test       # Run test suite
python main.py --setup      # Run setup wizard
python main.py --status     # Show status and configuration
python main.py --help       # Show all options

🔒 Security

• Store credentials in environment variables, not config files
• Use HTTPS for Superset connections
• Regularly rotate authentication tokens
• Limit MCP server access to trusted clients
• Monitor server logs for suspicious activity
• Automated security scanning in CI/CD pipeline

🤝 Contributing

We welcome contributions! Please see our for details.

Quick Contributing Steps:

1. Fork the repository: https://github.com/chrissmartin/apache-superset-mcp/fork
2. Clone your fork:

   git clone https://github.com/your-username/apache-superset-mcp.git
   cd apache-superset-mcp
   

3. Set up development environment:

   make dev-setup
   

4. Make your changes and test:

   make quick-check
   apache-superset-mcp test
   

5. Use conventional commits:

   git commit -m "feat: add new MCP tool for dashboard filtering"
   

6. Submit a pull request: https://github.com/chrissmartin/apache-superset-mcp/compare

Ways to Contribute:

• 🐛 Report bugs: Issues
• 💡 Suggest features: Feature Requests
• 📖 Improve documentation
• 🧪 Add tests and examples
• 🔧 Add support for new MCP clients

Release Process:

• Automated CI/CD with semantic versioning
• See for details

📝 License

This project is licensed under the MIT License - see the file for details.

🌟 Features in Development

• Dashboard layout management
• Chart template system
• Bulk operations
• Advanced filtering
• Performance analytics
• Multi-instance support
• Enhanced error recovery
• Performance monitoring
• Advanced authentication methods

💡 Use Cases

• Data Analysts: Create and manage dashboards through natural language
• Developers: Integrate Superset into development workflows
• DevOps: Automate dashboard creation and maintenance
• Business Users: Explore data without learning Superset UI
• Data Teams: Standardize dashboard creation processes

Get started in minutes: pip install apache-superset-mcp && apache-superset-mcp setup → Configure your client → Start exploring your data with AI! 🚀