StarRocks/mcp-server-starrocks

The StarRocks MCP Server acts as a bridge between AI assistants and StarRocks databases. It allows for direct SQL execution, database exploration, data visualization via charts, and retrieving detailed schema/data overviews without requiring complex client-side setup.
Features
- **Direct SQL Execution:** Run SELECT queries (read_query) and DDL/DML commands (write_query).
- **Database Exploration:** List databases and tables, retrieve table schemas (starrocks:// resources).
- **System Information:** Access internal StarRocks metrics and states via the proc:// resource path.
- **Detailed Overviews:** Get comprehensive summaries of tables (table_overview) or entire databases (db_overview), including column definitions, row counts, and sample data.
- **Data Visualization:** Execute a query and generate a Plotly chart directly from the results (query_and_plotly_chart).
- **Intelligent Caching:** Table and database overviews are cached in memory to speed up repeated requests. Cache can be bypassed when needed.
- **Flexible Configuration:** Set connection details and behavior via environment variables.
Prerequisites
- **Python 3.11 or newer.**
- A reachable **StarRocks** cluster (FE service). By default the server connects to localhost:9030 over the MySQL protocol.
- **uv** — a fast Python package and project manager (a modern replacement for pip + virtualenv) from Astral. This project uses uv to resolve dependencies, create the virtual environment, and launch the server. The uv run commands throughout this README automatically create an isolated environment and install the required dependencies on first use, so no manual pip install step is needed.
Installing uv
See the official uv installation guide for other options. After installing, verify it is on your PATH:
Installation
You generally do **not** need to install the package manually — the MCP host launches it for you via uv (see Configuration below). uv fetches the package and its dependencies on demand.
To run it directly for testing or development:
Configuration
The MCP server is typically run via an MCP host. Configuration is passed to the host, specifying how to launch the StarRocks MCP server process.
**Using Streamable HTTP (recommended):**
To start the server in Streamable HTTP mode:
First test that the connection to StarRocks is OK (9030 is the StarRocks MySQL protocol port, not the HTTP server port):
Start the server:
Then config the MCP like this:
**Using Docker:**
Build the image:
Build and push a versioned image:
Start the server in Streamable HTTP mode:
Then configure the MCP client with:
**Using uv with installed package (individual environment variables):**
**Using uv with installed package (connection URL):**
**Using uv with local directory (for development):**
bash
security add-generic-password -U -a root -s mcp-server-starrocks -w 'secret'
bash
security find-generic-password -a root -s mcp-server-starrocks -w
bash
export STARROCKS_URL=root@localhost:9030/test_db
export STARROCKS_PASSWORD_KEYCHAIN_SERVICE=mcp-server-starrocks
export STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT=root
bash
sudo -v
sudo install -d -m 0700 /etc/credstore.encrypted