analyze_query
Analyze a query and get analyze result using query profile. Use set_session_db to set a per-session default database
LABSCO SUMMARY
The ranking tools are the reason to install this rather than keep a SQL client open.
One tool reads visit counts out of the audit log and another ranks tables by health score — questions you would otherwise write and then maintain SQL for. The rest is shaped to keep large output away from the model: a query result can be redirected to a file, the table overview caps its sample at three rows, and both overview tools answer from cache unless refreshed. The dump-and-profile tool is the deliberate exception, and its own description warns the output is very large.
What it is
StarRocks' own server over a cluster: SQL execution, query profiling, audit-log-derived table rankings and a chart path, plus starrocks:// and proc:// resources for schemas and internal system state.
What you get
- Result-returning queries and DDL or DML statements kept in separate tools, with a large result written to a file as CSV, TSV, JSON or JSONL instead of returned inline
- Query analysis from the cluster's own profile — by query id or by SQL — plus a full dump and profile collection for the cases that need offline processing
- Rankings the cluster computes about itself: hottest tables by audit-log visit count within a time window, and worst tables by health score
- Orientation before querying — a table overview with columns, up to 3 sample rows and a row count, and a database summary with table schemas and sizes, both served from cache until a refresh is asked for
- A chart path that runs SQL and a Plotly expression together, returned as an image or written out as an interactive HTML file
- A per-session default database, so the db argument stops being repeated on every call
- Internal cluster state as readable resources: frontends, backends, partitions, transactions, jobs and catalogs under proc://
Requirements
Python 3.11 or newer, uv, and a reachable StarRocks FE service — port 9030, the MySQL protocol port rather than the HTTP one. Connection details come either as STARROCKS_HOST, STARROCKS_PORT, STARROCKS_USER, STARROCKS_PASSWORD and STARROCKS_DB, or as one STARROCKS_URL that overrides them; on macOS the password can come from Keychain instead. Grant the account only what you intend, since the write tool runs DDL and DML. TLS is not verified unless you set a CA and turn verification on. Files that tools write land on the machine running the server, which is not the client machine for an HTTP deployment. Apache-2.0.
Setup effort
One command — uvx mcp-server-starrocks --mode streamable-http --port 8000
USE CASES
01
Working out why a dashboard query got slow
Run the analysis against the cluster's own query profile, and collect the full dump when the profile alone does not explain it — that output is large enough to need processing before it is read.
02
Getting oriented in a database you did not build
Set the session default so the database argument stops repeating, summarise the tables and their sizes, then open the one that matters with its columns, a few sample rows and a row count.
03
Deciding where maintenance time is worth spending
The cluster already knows which tables are being hit and which are in poor shape — one ranks by audit-log visit count over a window, the other by health score.
04
Turning a result into something to look at
One call carries both the SQL and the Plotly expression, so the query result is charted without a separate export step.
05
Pulling a result set too big for the conversation
Give the query an output file and a format; what comes back is a path, a byte count, a row count and a short preview rather than the rows themselves.
10 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
collect_query_dump_and_profile
Run a query to get it's query dump and profile, output very large, need special tools to do further processing
db_summary
Quickly get summary of a database with tables' schema and size information. Use set_session_db to set a per-session default database
query_and_plotly_chart
using sql query to extract data from database, then using python plotly_expr to generate a chart for UI to display. Use set_session_db to set a per-session default database
read_query
Execute a SELECT query or commands that return a ResultSet. Set output_file to write the full result to disk instead of returning it inline (useful for large results).. Use set_session_db to set a per-session default database
set_session_db
Set or clear the default database for THIS MCP session. Subsequent tool calls without an explicit db argument will use this database. Pass an empty string or null to clear and fall back to the server's global default. Returns the new effective default for this session.
table_overview
Get an overview of a specific table: columns, sample rows (up to 3), and total row count. Uses cache unless refresh=true. Use set_session_db to set a per-session default database
top_bad_tables
Get top bad tables by table health score
top_hot_tables
Get top hot tables by audit-log visit count
write_query
Execute a DDL/DML or other StarRocks command that do not have a ResultSet. Use set_session_db to set a per-session default database
BEFORE YOU INSTALL
What to know first
Tools you get
10 tools when we connected. The documented db_overview no longer exists; call db_summary instead. collect_query_dump_and_profile and set_session_db are undocumented.
Requires
- uvx on PATH
- Python 3.11 or later
Where it runs
Both documented setups run the server on your machine.
CONTEXT COST
Light Standing cost
Rated by the size of the 10 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
uvx mcp-server-starrocks --mode streamable-http --port 8000MCP Clients
Any MCP client — stdio
ANY MCP CLIENT — STDIO · JSON
{
"mcpServers": {
"mcp-server-starrocks": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-server-starrocks",
"mcp-server-starrocks"
],
"env": {
"STARROCKS_URL": "root:password@localhost:9030/my_database"
}
}
}
}Any MCP client — HTTP
ANY MCP CLIENT — HTTP · JSON
{
"mcpServers": {
"mcp-server-starrocks": {
"url": "http://localhost:8000/mcp"
}
}
}
