StarRocks MCP Server

Official MCP server for StarRocks, enabling AI assistants to directly execute SQL, explore database schemas, analyze performance, and generate visualizations.

Core Features#

The official adapter connecting AI models to the StarRocks OLAP database, exposing tools via the Model Context Protocol (MCP):

SQL Execution Tools#

read_query: Execute SELECT, SHOW, DESCRIBE and other result-set-returning commands
write_query: Execute DDL (CREATE/ALTER/DROP) and DML (INSERT/UPDATE/DELETE) commands
analyze_query: Analyze query performance via Query Profile or Explain Analyze

Database Exploration#

table_overview: Get table structure, row count, and sample data (with memory caching)
db_overview: Get overview of all tables in a specified database
Resource paths: starrocks:///databases, starrocks:///{db}/tables, starrocks:///{db}/{table}/schema

System Information Access#

Access StarRocks internal system information via proc:///{path}
Supported paths: /frontends, /backends, /compute_nodes, /dbs, /transactions, /jobs, /catalog, etc.

Data Visualization#

query_and_plotly_chart: Execute SQL and generate charts using Plotly Express, returning Base64 PNG images

Technical Highlights#

Connection Architecture#

Standard MySQL Protocol: Connect via mysql.connector (default port 9030)
Arrow Flight SQL: High-performance connection using ADBC driver (enable by setting STARROCKS_FE_ARROW_FLIGHT_SQL_PORT)

Smart Caching#

Table and database overviews use memory caching with (database_name, table_name) tuple keys
Bypass cache with refresh=true parameter
Control overview text length via STARROCKS_OVERVIEW_LIMIT environment variable (default 20000 characters)

Transport Modes#

stdio mode (default)
Streamable HTTP mode (recommended)
SSE mode

Security Mechanisms#

SQL injection protection: Parameterized queries and backtick escaping
Plotly expression validation: AST parsing to prevent code injection

Installation & Configuration#

Installation#

pip install mcp-server-starrocks
# Or using uv
uv run --with mcp-server-starrocks mcp-server-starrocks

Environment Variables#

STARROCKS_URL: Connection string (highest priority), format user:password@host:port/database
STARROCKS_HOST / PORT / USER / PASSWORD / DB: Separate configuration
STARROCKS_FE_ARROW_FLIGHT_SQL_PORT: Enable high-performance Arrow Flight connection
MCP_TRANSPORT_MODE: Transport mode

Use Cases#

Natural language-driven database query and analysis (Text-to-SQL execution)
AI Agent autonomous database structure exploration and performance diagnosis
Integration with MCP-supporting clients (Claude Desktop, Cursor, etc.) for real-time data conversations

Core Modules#

server.py: Main service implementation, defining MCP Tools and Resources
db_client.py: Database connection pool management
db_summary_manager.py: Metadata caching and overview generation
connection_health_checker.py: Connection status monitoring and auto-reconnection