Superset MCP Server

Superset MCP Server - TypeScript Implementation

A comprehensive TypeScript implementation of the Model Context Protocol (MCP) server for Apache Superset, enabling AI assistants to interact with and control Superset instances programmatically through multiple transport methods.

📚 Based on: This TypeScript implementation is derived from the original Python MCP server: aptro/superset-mcp

🚀 Key Features

Multiple Transport Modes

This server supports three different transport modes for maximum deployment flexibility:

🔧 Stdio Transport (Default) - Traditional MCP client integration
🌐 SSE Transport - Web applications with Server-Sent Events
⚡ StreamableHttp Transport - Modern full-duplex HTTP streaming (Recommended for production)

Complete Superset API Coverage

45+ MCP Tools covering all major Superset functionality
Authentication Management: Token-based auth with automatic refresh using proper OAuth 2.0 patterns
Dashboard Operations: Full CRUD operations for dashboards
Chart Management: Complete chart/visualization lifecycle management
Database Integration: Connection management, schema exploration, SQL validation
Dataset Operations: Dataset creation and management
SQL Lab Integration: Query execution, cost estimation, result export
Advanced Features: Tag management, exploration tools, advanced data types
User & System: User management, activity tracking, system configuration

Production-Ready Features

Robust Error Handling: Comprehensive error responses with detailed context
Session Management: Cookie-aware CSRF token handling
Token Management: Automatic token refresh with proper refresh token usage
Type Safety: Full TypeScript implementation with comprehensive type definitions
Multiple Deployment Options: Support for different client architectures

📋 Prerequisites

Node.js 16+
TypeScript 4.0+
A running Apache Superset instance (v1.0+)
Valid Superset credentials with appropriate permissions

🛠️ Installation

Clone and setup the repository:
git clone <your-typescript-repository-url> cd superset-mcp-ts npm install
Configure environment variables:Create a .env file in the root directory:
SUPERSET_BASE_URL=http://localhost:8088 SUPERSET_USERNAME=your_username SUPERSET_PASSWORD=your_password
Build the TypeScript code:
npm run build

🚀 Quick Start Guide

Transport Mode Selection

Stdio Transport (Default - MCP Clients)

npm run start:stdio

Perfect for Claude Desktop and other MCP clients.

SSE Transport (Web Applications)

npm run start:sse
# Server runs on http://localhost:3000
# Health check: curl http://localhost:3000/health

Ideal for web applications requiring real-time updates.

StreamableHttp Transport (Production Recommended)

npm run start:http
# Server runs on http://localhost:3000
# Health check: curl http://localhost:3000/health

Best performance for high-throughput applications.

Development Workflow

# Development with auto-reload
npm run dev              # Stdio mode
npm run dev:sse         # SSE mode  
npm run dev:http        # HTTP mode

# Production deployment
npm start               # Uses stdio by default

Claude Desktop Integration

Add this configuration to your Claude Desktop MCP settings (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "superset-ts": {
      "command": "node",
      "args": ["/absolute/path/to/your/superset-mcp-ts/build/index.js"],
      "env": {
        "SUPERSET_BASE_URL": "http://localhost:8088",
        "SUPERSET_USERNAME": "admin",
        "SUPERSET_PASSWORD": "admin"
      }
    }
  }
}

📚 Complete API Reference

Authentication Tools

Tool	Description	Parameters
`superset_auth_check_token_validity`	Verify current token status	None
`superset_auth_refresh_token`	Refresh access token using refresh token	None
`superset_auth_authenticate_user`	Login with credentials	`username?`, `password?`, `refresh?`

Dashboard Management

Tool	Description	Parameters
`superset_dashboard_list`	Get all dashboards	None
`superset_dashboard_get_by_id`	Get specific dashboard	`dashboard_id: number`
`superset_dashboard_create`	Create new dashboard	`dashboard_title: string`, `json_metadata?: object`
`superset_dashboard_update`	Update dashboard	`dashboard_id: number`, `data: object`
`superset_dashboard_delete`	Delete dashboard	`dashboard_id: number`

Chart/Visualization Tools

Tool	Description	Parameters
`superset_chart_list`	Get all charts	None
`superset_chart_get_by_id`	Get specific chart	`chart_id: number`
`superset_chart_create`	Create new chart	`slice_name`, `datasource_id`, `datasource_type`, `viz_type`, `params`
`superset_chart_update`	Update chart	`chart_id: number`, `data: object`
`superset_chart_delete`	Delete chart	`chart_id: number`

Database Connection Management

Tool	Description	Parameters
`superset_database_list`	Get all databases	None
`superset_database_get_by_id`	Get database details	`database_id: number`
`superset_database_create`	Create database connection	`engine`, `configuration_method`, `database_name`, `sqlalchemy_uri`
`superset_database_test_connection`	Test database connection	`database_data: object`
`superset_database_update`	Update database	`database_id: number`, `data: object`
`superset_database_delete`	Delete database	`database_id: number`
`superset_database_get_tables`	Get database tables	`database_id: number`
`superset_database_schemas`	Get database schemas	`database_id: number`
`superset_database_get_catalogs`	Get database catalogs	`database_id: number`
`superset_database_get_connection`	Get connection info	`database_id: number`
`superset_database_get_function_names`	Get available functions	`database_id: number`
`superset_database_get_related_objects`	Get related charts/dashboards	`database_id: number`
`superset_database_validate_sql`	Validate SQL syntax	`database_id: number`, `sql: string`
`superset_database_validate_parameters`	Validate connection params	`parameters: object`

Dataset Management

Tool	Description	Parameters
`superset_dataset_list`	Get all datasets	None
`superset_dataset_get_by_id`	Get dataset details	`dataset_id: number`
`superset_dataset_create`	Create dataset	`table_name`, `database_id`, `schema?`, `owners?`

SQL Lab & Query Execution

Tool	Description	Parameters
`superset_sqllab_execute_query`	Execute SQL query	`database_id: number`, `sql: string`
`superset_sqllab_get_saved_queries`	Get saved queries	None
`superset_sqllab_format_sql`	Format SQL	`sql: string`
`superset_sqllab_get_results`	Get query results	`key: string`
`superset_sqllab_estimate_query_cost`	Estimate query cost	`database_id`, `sql`, `schema?`
`superset_sqllab_export_query_results`	Export results to CSV	`client_id: string`
`superset_sqllab_get_bootstrap_data`	Get SQL Lab bootstrap data	None

Query Management

Tool	Description	Parameters
`superset_query_list`	List all queries	None
`superset_query_get_by_id`	Get query details	`query_id: number`
`superset_query_stop`	Stop running query	`client_id: string`

Saved Query Operations

Tool	Description	Parameters
`superset_saved_query_get_by_id`	Get saved query	`query_id: number`
`superset_saved_query_create`	Create saved query	`query_data: object`

User & Activity Management

Tool	Description	Parameters
`superset_user_get_current`	Get current user info	None
`superset_user_get_roles`	Get user roles	None
`superset_activity_get_recent`	Get recent activity	None

Tag System

Tool	Description	Parameters
`superset_tag_list`	Get all tags	None
`superset_tag_create`	Create new tag	`name: string`
`superset_tag_get_by_id`	Get tag details	`tag_id: number`
`superset_tag_objects`	Get tagged objects	None
`superset_tag_delete`	Delete tag	`tag_id: number`
`superset_tag_object_add`	Add tag to object	`object_type`, `object_id`, `tag_name`
`superset_tag_object_remove`	Remove tag from object	`object_type`, `object_id`, `tag_name`

Exploration & Advanced Features

Tool	Description	Parameters
`superset_explore_form_data_create`	Create exploration form data	`form_data: object`
`superset_explore_form_data_get`	Get form data	`key: string`
`superset_explore_permalink_create`	Create permalink	`state: object`
`superset_explore_permalink_get`	Get permalink	`key: string`
`superset_advanced_data_type_convert`	Convert data types	`value`, `target_type`
`superset_advanced_data_type_list`	List data types	None

System & Configuration

Tool	Description	Parameters
`superset_config_get_base_url`	Get Superset URL	None
`superset_menu_get`	Get menu structure	None

🏗️ Architecture & Technical Details

Project Structure

src/
├── index.ts              # Main entry point with transport selection
├── server.ts             # Core MCP server implementation
├── transports/
│   ├── stdio.ts          # Stdio transport implementation
│   ├── sse.ts            # Server-Sent Events transport
│   └── streamable-http.ts # HTTP streaming transport
├── types/                # TypeScript type definitions
└── utils/                # Utility functions

Key Technical Implementations

Authentication System

OAuth 2.0 Compliant: Proper access/refresh token handling
Session Management: Cookie-aware CSRF token support
Auto-Refresh: Transparent token renewal on expiration
Secure Storage: File-based token persistence

Error Handling

Comprehensive Coverage: All API calls wrapped with error handlers
Detailed Context: Meaningful error messages with troubleshooting hints
Graceful Degradation: Fallback behaviors for common failure scenarios

Transport Layer

Modular Design: Pluggable transport implementations
Standards Compliant: MCP specification adherence
Production Ready: Health checks, proper HTTP status codes
Development Friendly: Hot reload and debugging support

Dependencies & Tech Stack

@modelcontextprotocol/sdk: MCP TypeScript SDK v1.17.1
axios: HTTP client for Superset API communication
dotenv: Environment variable management
TypeScript: Type safety and modern JavaScript features
Node.js: Runtime environment

🔧 Development Guide

Available Scripts

# Building
npm run build            # Compile TypeScript
npm run build:watch      # Build with file watching

# Development
npm run dev             # Default stdio development
npm run dev:stdio       # Stdio transport development
npm run dev:sse         # SSE transport development  
npm run dev:http        # HTTP transport development

# Production
npm start               # Production mode (stdio)
npm run start:stdio     # Production stdio
npm run start:sse       # Production SSE
npm run start:http      # Production HTTP

# Code Quality
npm run lint            # ESLint checking
npm run lint:fix        # Auto-fix ESLint issues
npm run format          # Prettier formatting
npm run type-check      # TypeScript type checking

Adding New Tools

Add tool definition in ListToolsRequestSchema handler
Implement case handler in CallToolRequestSchema handler
Add proper parameter validation with TypeScript types
Include error handling with meaningful messages
Update documentation in this README

Testing Locally

# Test with curl (for HTTP/SSE transports)
curl http://localhost:3000/health

# Test authentication
npm run dev:stdio
# Then use Claude Desktop or other MCP client to test tools

🚀 Deployment Options

Docker Deployment

FROM node:16-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY build/ ./build/
EXPOSE 3000
CMD ["npm", "run", "start:http"]

PM2 Process Management

{
  "name": "superset-mcp",
  "script": "build/index.js",
  "env": {
    "NODE_ENV": "production",
    "SUPERSET_BASE_URL": "https://your-superset.com",
    "TRANSPORT": "http"
  }
}

Cloud Deployment

AWS: Deploy as Lambda function or ECS container
Google Cloud: Cloud Run or Compute Engine
Azure: Container Instances or App Service
Heroku: Direct deployment with buildpack

🔍 Troubleshooting

Common Issues

Authentication Problems

# Check Superset connectivity
curl $SUPERSET_BASE_URL/api/v1/security/login

# Verify credentials
grep SUPERSET .env

Token Refresh Issues

Problem: "No refresh token available"
Solution: Re-authenticate with superset_auth_authenticate_user
Cause: Refresh token expired or not properly stored

CSRF Token Errors

Problem: "CSRF token missing"
Solution: Server automatically handles CSRF tokens
Check: Ensure cookies are enabled in your environment

Debug Mode

# Enable debug logging
DEBUG=superset-mcp:* npm run dev

📈 Performance Considerations

Connection Pooling: Axios instance reuse
Token Caching: Minimize authentication requests
Error Caching: Avoid repeated failed requests
Batch Operations: Use list operations when possible

🤝 Contributing

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Follow TypeScript best practices
Add comprehensive error handling
Update documentation
Test thoroughly with Superset instance
Submit pull request

Code Style

Use Prettier for formatting
Follow ESLint rules
Maintain TypeScript strict mode
Include JSDoc comments for public functions

📄 License

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

🙏 Acknowledgments

We extend our gratitude to the following projects and communities that made this implementation possible:

Core Foundations

aptro/superset-mcp - The original Python MCP server implementation that serves as the foundation for this TypeScript version. This project provides complete feature parity while adding multiple transport options and enhanced type safety.

Key Dependencies & Technologies

Apache Superset - The modern business intelligence web application that this server integrates with
Model Context Protocol (MCP) - The protocol specification developed by Anthropic that enables AI assistants to securely integrate with external tools and data sources
Anthropic Claude - The AI assistant platform that pioneered MCP integration

Development Ecosystem

TypeScript - For providing excellent type safety and developer experience
Node.js - The runtime environment that powers this server
@modelcontextprotocol/sdk - The official TypeScript SDK for MCP implementations
Axios - For reliable HTTP client functionality
ESLint & Prettier - For maintaining code quality and consistency

Community & Support

Open Source Community - For the collaborative spirit that enables projects like this to exist and thrive
Apache Software Foundation - For maintaining the open-source Superset platform
TypeScript Community - For excellent tooling, type definitions, and best practices that make TypeScript development a pleasure

Special Recognition

This TypeScript implementation maintains full compatibility with the original Python version while extending capabilities through:

Multiple transport mechanisms (Stdio, SSE, HTTP)
Enhanced type safety and developer experience
Production-ready deployment options
Comprehensive error handling and logging

Thank you to all contributors, users, and the broader open-source ecosystem that makes innovative integrations like this possible.

📞 Support

Issues: Open GitHub issues for bugs and feature requests
Documentation: Check this README and inline code comments
Original Reference: See aptro/superset-mcp for additional context

🌟 This TypeScript implementation provides complete feature parity with the original Python version while adding multiple transport options and enhanced type safety for modern development workflows.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables AI assistants to interact with Apache Superset instances programmatically, providing 45+ tools for dashboard management, chart creation, database operations, SQL execution, and complete Superset API coverage. Supports multiple transport modes including stdio, SSE, and HTTP streaming for flexible deployment options.

Related MCP Servers

Metabase Server MCP
berry-street
-
security
F
license
-
quality
Enables AI assistants to interact with Metabase, providing access to dashboards, questions, databases, and tools for executing queries and viewing data through natural language.
Last updated -
JavaScript
MCP Server for Asana
cristip73
-
security
A
license
-
quality
This server implementation allows AI assistants to interact with Asana's API, enabling users to manage tasks, projects, workspaces, and comments through natural language requests.
Last updated -
746
TypeScript
MIT License
Superset MCP Integration
aptro
-
security
A
license
-
quality
MCP server enabling AI agents to programmatically connect to and control Apache Superset instances, allowing users to manage dashboards, charts, databases, datasets, and run SQL queries through natural language interactions.
Last updated -
75
Python
MIT License
Superset MCP Server
LiusCraft
A
security
F
license
A
quality
A Model Context Protocol server that enables large language models to interact with Apache Superset databases through REST API, supporting database queries, table lookups, field information retrieval, and SQL execution.
Last updated -
4
4
TypeScript

View all related MCP servers