mcp-server-starrocks: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

StarRocks Official MCP Server - A bridge between AI assistants and StarRocks databases, built using FastMCP framework. Enables direct SQL execution, database exploration, data visualization, and schema introspection through the Model Context Protocol (MCP).

Development Commands

Local Development:

# Run the server directly for testing
uv run mcp-server-starrocks

# Run with test mode to verify table overview functionality
uv run mcp-server-starrocks --test

# Run in Streamable HTTP mode (recommended for integration)
export MCP_TRANSPORT_MODE=streamable-http
uv run mcp-server-starrocks

Package Management:

# Install dependencies (handled by uv automatically)
uv sync

# Build package
uv build

Architecture Overview

Core Components

• src/mcp_server_starrocks/server.py: Main server implementation containing all MCP tools, resources, and database connection logic
• src/mcp_server_starrocks/__init__.py: Entry point that starts the async server

Connection Architecture

The server supports two connection modes:

• Standard MySQL Protocol: Default connection using mysql.connector
• Arrow Flight SQL: High-performance connection using ADBC drivers (enabled when STARROCKS_FE_ARROW_FLIGHT_SQL_PORT is set)

Connection management uses a global singleton pattern with automatic reconnection handling.

Tool Categories

1. Query Execution Tools:

   • read_query: Execute SELECT and other result-returning queries
   • write_query: Execute DDL/DML commands
   • analyze_query: Query performance analysis via EXPLAIN ANALYZE

2. Overview Tools with Caching:

   • table_overview: Get table schema, row count, and sample data (cached)
   • db_overview: Get overview of all tables in a database (uses table cache)

3. Visualization Tool:

   • query_and_plotly_chart: Execute query and generate Plotly charts from results