🚀 Superset MCP Server (Streamable HTTP)

MCP (Model Context Protocol) Server untuk Apache Superset yang memungkinkan integrasi chatbot dengan Superset untuk membuat dashboard, chart, dan mengeksekusi query SQL secara programatis.

✨ Fitur

• 📊 Dashboard Management - List, get, create dashboard dan tambahkan chart ke dashboard
• 📈 Chart Management - List, get, create chart dengan auto-detection schema
• 🗃️ Dataset Management - List datasets dan get schema kolom
• 🔍 SQL Execution - Eksekusi query SQL langsung ke database Superset
• 🔄 Stateless HTTP - Menggunakan Streamable HTTP transport untuk kompatibilitas dengan Open WebUI
• 🔐 Auto Authentication - Otomatis login dan refresh token ke Superset

🛠️ Teknologi

• Runtime: Node.js + TypeScript
• Transport: Express.js + JSON-RPC 2.0
• Protocol: MCP (Model Context Protocol)
• Client: Axios untuk HTTP requests

📋 Prasyarat

• Node.js v18 atau lebih baru
• Apache Superset yang sudah running
• NPM atau Yarn

⚡ Quick Start

1. Clone & Install Dependencies

git clone <repository-url>
cd superset-mcp
npm install

2. Konfigurasi Environment

Salin file .env.example ke .env dan sesuaikan konfigurasinya:

cp .env.example .env

Isi konfigurasi di file .env:

# Superset Configuration
SUPERSET_URL=http://localhost:8088
SUPERSET_USERNAME=admin
SUPERSET_PASSWORD=admin

# MCP Server Configuration
MCP_PORT=3000

3. Build & Run

# Build TypeScript
npm run build

# Jalankan server
npm start

Atau untuk development dengan hot-reload:

npm run dev

4. Verifikasi Server

Akses health check endpoint:

curl http://localhost:3000/health

Response yang diharapkan:

{
  "status": "ok",
  "server": "superset-mcp",
  "version": "1.0.0",
  "mode": "stateless",
  "tools": ["list_dashboards", "get_dashboard", "create_dashboard", ...]
}

🔌 Integrasi dengan Open WebUI

Konfigurasi di Open WebUI

1. Buka Admin Panel → Tools → Tool Connections
2. Tambahkan MCP Server baru:
   • Name: Superset MCP
   • Type: MCP (Streamable HTTP)
   • URL: http://YOUR_SERVER_IP:3000/mcp
3. Save dan test koneksi

🔧 Available Tools

Dashboard Tools

Tool	Deskripsi
list_dashboards	Mendapatkan semua dashboard yang tersedia
get_dashboard	Detail dashboard termasuk chart-chart di dalamnya
create_dashboard	Membuat dashboard baru
add_chart_to_dashboard	Menambahkan satu chart ke dashboard
add_charts_to_dashboard	Menambahkan multiple charts ke dashboard (recommended)

Chart Tools

Tool	Deskripsi
list_charts	Mendapatkan semua chart yang tersedia
get_chart	Detail konfigurasi chart
get_chart_data	Fetch data dari chart
create_chart	Membuat chart baru (manual config)
create_chart_auto	Membuat chart dengan auto-detection schema

Dataset Tools

Tool	Deskripsi
list_datasets	Mendapatkan semua datasets/tables
get_dataset_schema	Mendapatkan definisi kolom dari dataset

SQL Tools

Tool	Deskripsi
list_databases	Mendapatkan semua koneksi database
execute_sql	Eksekusi query SQL ke database

📚 Contoh Penggunaan

Membuat Chart dengan Auto-Detection

"Buatkan bar chart untuk dataset sales_data yang menampilkan total revenue per bulan"

AI akan menggunakan create_chart_auto untuk:

1. Menganalisis schema dataset
2. Mendeteksi kolom waktu (x_axis)
3. Mendeteksi kolom numeric untuk metrics
4. Membuat chart dengan konfigurasi optimal

Membuat Dashboard dengan Multiple Charts

"Buatkan dashboard Sales Overview dengan 3 chart: line chart revenue, pie chart by category, dan table top products"

AI akan:

1. create_dashboard - Membuat dashboard baru
2. create_chart_auto (3x) - Membuat setiap chart
3. add_charts_to_dashboard - Menambahkan semua chart sekaligus dengan layout optimal

🏗️ Struktur Project

superset-mcp/
├── src/
│   ├── index.ts          # Entry point
│   ├── server.ts         # Express server & MCP tools
│   └── superset-client.ts # Superset API client
├── dist/                  # Compiled JavaScript
├── .env                   # Environment variables
├── .env.example           # Example environment
├── package.json
├── tsconfig.json
└── README.md

🔗 API Endpoints

Endpoint	Method	Deskripsi
/health	GET	Health check
/mcp	POST	MCP JSON-RPC requests
/mcp	GET	SSE streaming (keepalive)
/mcp	DELETE	Session cleanup

⚙️ Environment Variables

Variable	Default	Deskripsi
SUPERSET_URL	http://localhost:8088	URL Superset instance
SUPERSET_USERNAME	admin	Username untuk login
SUPERSET_PASSWORD	admin	Password untuk login
MCP_PORT	3000	Port untuk MCP server

🐛 Troubleshooting

1. Authentication Failed

Pastikan credentials di .env sudah benar. Server akan otomatis refresh token jika expired.

2. CORS Error

Server sudah dikonfigurasi untuk menerima requests dari semua origin. Jika masih error, pastikan firewall tidak memblokir port.

3. Chart Tidak Menampilkan Data

Gunakan create_chart_auto daripada create_chart untuk auto-detection metrics dan dimensions.

📄 License

MIT License

🤝 Contributing

Contributions are welcome! Feel free to open issues atau pull requests.