by StarRocks
StarRocks MCP (Model Context Protocol) Server
# Add to your Claude Code skills
git clone https://github.com/StarRocks/mcp-server-starrocksThe 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.
SELECT queries (read_query) and DDL/DML commands (write_query).starrocks:// resources).proc:// resource path.table_overview) or entire databases (db_overview), including column definitions, row counts, and sample data.query_and_plotly_chart).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):
No comments yet. Be the first to share your thoughts!
To start the server in Streamable HTTP mode:
First test connect is ok:
$ STARROCKS_URL=root:@localhost:8000 uv run mcp-server-starrocks --test
Start the server:
uv run mcp-server-starrocks --mode streamable-http --port 8000
Then config the MCP like this:
{
"mcpServers": {
"mcp-server-starrocks": {
"url": "http://localhost:8000/mcp"
}
}
}
Using uv with installed package (individual environment variables):
{
"mcpServers": {
"mcp-server-starrocks": {
"command": "uv",
"args": ["run", "--with", "mcp-server-starrocks", "mcp-server-starrocks"],
"env": {
"STARROCKS_HOST": "default localhost",
"STARROCKS_PORT": "default 9030",
"STARROCKS_USER": "default root",
"STARROCKS_PASSWORD": "default empty",
"STARROCKS_DB": "default empty"
}
}
}
}
Using uv with installed package (connection URL):
{
"mcpServers": {
"mcp-server-starrocks": {
"command": "uv",
"args": ["run", "--with", "mcp-server-starrocks", "mcp-server-starrocks"],
"env": {
"STARROCKS_URL": "root:password@localhost:9030/my_database"
}
}
}
}
Using uv with local directory (for development):
{
"mcpServers": {
"mcp-server-starrocks": {
"command": "uv",
"args": [
"--directory",
"path/to/mcp-server-starrocks", // <-- Update this path
"run",
"mcp-server-starrocks"
],
"env": {
"STARROCKS_HOST": "default localhost",
"STARROCKS_PORT": "default 9030",
"STARROCKS_USER": "default root",
"STARROCKS_PASSWORD": "default empty",
"STARROCKS_DB": "default empty"
}
}
}
}
Using uv with local directory and connection URL:
{
"mcpServers": {
"mcp-server-starrocks": {
"command": "uv",
"args": [
"--directory",
"path/to/mcp-server-starrocks", // <-- Update this path
"run",
"mcp-server-starrocks"
],
"env": {
"STARROCKS_URL": "root:password@localhost:9030/my_database"
}
}
}
}
Command-line Arguments:
The server supports the following command-line arguments:
uv run mcp-server-starrocks --help
--mode {stdio,sse,http,streamable-http}: Transport mode (default: stdio or MCP_TRANSPORT_MODE env var)--host HOST: Server host for HTTP modes (default: localhost)--port PORT: Server port for HTTP modes--test: Run in test mode to verify functionalityExamples:
# Start in streamable HTTP mode on custom host/port
uv run mcp-server-starrocks --mode streamable-http --host 0.0.0.0 --port 8080
# Start in stdio mode (default)
uv run mcp-server-starrocks --mode stdio
# Run test mode
uv run mcp-server-starrocks --test
url field should point to the Streamable HTTP endpoint of your MCP server (adjust host/port as needed).Note: The
sse(Server-Sent Events) mode is deprecated and no longer maintained. Please use Streamable HTTP mode for all new integrations.
Environment Variables:
You can configure StarRocks connection using either individual environment variables or a single connection URL:
Option 1: Individual Environment Variables
STARROCKS_HOST: (Optional) Hostname or IP address of the StarRocks FE service. Defaults to localhost.STARROCKS_PORT: (Optional) MySQL protocol port of the StarRocks FE service. Defaults to 9030.STARROCKS_USER: (Optional) StarRocks username. Defaults to root.STARROCKS_PASSWORD: (Optional) StarRocks password. Defaults to empty string.STARROCKS_DB: (Optional) Default database to use if not specified in tool arguments or resource URIs. If set, the connection will attempt to USE this database. Tools like table_overview and db_overview will use this if the database part is omitted in their arguments. Defaults to empty (no default database).Option 2: Connection URL (takes precedence over individual variables)
STARROCKS_URL: (Optional) A connection URL string that contains all connection parameters in a single variable. Format: [<schema>://]user:password@host:port/database. The schema part is optional. When this variable is set, it takes precedence over the individual STARROCKS_HOST, STARROCKS_PORT, STARROCKS_USER, STARROCKS_PASSWORD, and STARROCKS_DB variables.
Examples:
root:mypass@localhost:9030/test_dbmysql://admin:secret@db.example.com:9030/productionstarrocks://user:pass@192.168.1.100:9030/analyticsSTARROCKS_OVERVIEW_LIMIT: (Optional) An approximate character limit for the total text generated by overview tools (table_overview, db_overview) when fetching data to populate the cache. This helps prevent excessive memory usage for very large schemas or numerous tables. Defaults to 20000.
STARROCKS_MYSQL_AUTH_PLUGIN: (Optional) Specifies the authentication plugin to use when connecting to the StarRocks FE service. For example, set to mysql_clear_password if your StarRocks deployment requires clear text password authentication (such as when using certain LDAP or external authentication setups). Only set this if your environment specifically requires it; otherwise, the default auth_plugin is used.
MCP_TRANSPORT_MODE: (Optional) Communication mode that specifies how the MCP Server exposes its services. Available options:
stdio (default): Communicates through standard input/output, suitable for MCP Host hosting.streamable-http (Streamable HTTP): Starts as a Streamable HTTP Server, supporting RESTful API calls.sse: (Deprecated, not recommended) Starts in Server-Sent Events (SSE) streaming mode, suitable for scenarios requiring streaming responses. Note: SSE mode is no longer maintained, it is recommended to use Streamable HTTP mode uniformly.read_query
SHOW, DESCRIBE).{
"query": "SQL query string",
"db": "database name (optional, uses default database if not specified)"
}
write_query
CREATE, ALTER, DROP), DML (INSERT, UPDATE, DELETE), or other StarRocks command that does not return a ResultSet.{
"query": "SQL command string",
"db": "database name (optional, uses default database if not specified)"
}
analyze_query
{
"uuid": "Query ID, a string composed of 32 hexadecimal digits formatted as 8-4-4-4-12",
"sql": "Query SQL to analyze",
"db": "database name (optional, uses default database if not specified)"
}
ANALYZE PROFILE FROM if uuid is provided, otherwise uses EXPLAIN ANALYZE if sql is provided.query_and_plotly_chart
{
"query": "SQL query to fetch data",
"plotly_expr": "Python expression string using 'px' (Plotly Express) and 'df' (DataFrame). Example: 'px.scatter(df, x=\"col1\", y=\"col2\")'",
"db": "database name (optional, uses default database if not specified)"
}