The StarRocks MCP Server bridges AI assistants and StarRocks databases, enabling:
SQL Execution: Run both read-only queries (read_query) and write operations (write_query) including DDL/DML commands.
Database Exploration: List databases (starrocks:///databases), tables within databases (starrocks:///{db}/tables), and retrieve table schemas (starrocks:///{db}/{table}/schema).
Comprehensive Overviews: Get detailed summaries of tables (table_overview) or entire databases (db_overview), including schema definitions, row counts, and sample data.
Data Visualization: Generate Plotly charts directly from query results (query_and_plotly_chart).
System Information: Access StarRocks internal metrics and states via a /proc-like interface (proc:///{+path}).
Intelligent Caching: Cache database information for faster repeated requests, with bypass options available.
Flexible Configuration: Customize connection details and behavior using environment variables.
Provides access to system information through a proc-like interface, allowing exploration of node status, database details, and system metrics similar to the Linux /proc filesystem.
Enables execution of SQL queries against StarRocks databases using Python, supporting both read operations (SELECT queries) and write operations (DDL/DML commands).
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@StarRocks MCP Server show me the top 10 customers by total sales last month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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.
Related MCP server: starrocks-mcp
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.
uv# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# Or via Homebrew / pipx / pip
brew install uv
# pipx install uv
# pip install uvSee the official uv installation guide for other options. After installing, verify it is on your PATH:
uv --versionYou 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:
# Run the published package in a throwaway environment
uv run --with mcp-server-starrocks mcp-server-starrocks --help
# Or, from a local checkout of this repository
git clone https://github.com/starrocks/mcp-server-starrocks.git
cd mcp-server-starrocks
uv sync # create the virtual environment and install dependencies
uv run mcp-server-starrocks --helpThe 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):
$ STARROCKS_URL=root:@localhost:9030 uv run mcp-server-starrocks --testStart the server:
uv run mcp-server-starrocks --mode streamable-http --port 8000Then 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 functionality
Examples:
# 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 --testThe url field should point to the Streamable HTTP endpoint of your MCP server (adjust host/port as needed).
With this configuration, clients can interact with the server using standard JSON over HTTP POST requests. No special SDK is required.
All tool APIs accept and return standard JSON as described above.
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_PASSWORD_KEYCHAIN_SERVICE: (Optional, macOS only) Generic password service name to use when reading the password from Keychain. This is only used when no explicit password is provided via STARROCKS_PASSWORD or STARROCKS_URL.
STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT: (Optional, macOS only) Generic password account name to use when reading the password from Keychain. Defaults to the resolved StarRocks user.
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_db
mysql://admin:secret@db.example.com:9030/production
starrocks://user:pass@192.168.1.100:9030/analytics
Password precedence:
A password embedded in STARROCKS_URL wins, including an explicit empty password like user:@host:9030/db.
If STARROCKS_URL omits the password, STARROCKS_PASSWORD is used when set.
If neither explicit password source is set and STARROCKS_PASSWORD_KEYCHAIN_SERVICE is configured, the password is read from macOS Keychain.
macOS Keychain example
Store the password:
security add-generic-password -U -a root -s mcp-server-starrocks -w 'secret'Verify the stored password:
security find-generic-password -a root -s mcp-server-starrocks -wUse it with this server:
export STARROCKS_URL=root@localhost:9030/test_db
export STARROCKS_PASSWORD_KEYCHAIN_SERVICE=mcp-server-starrocks
export STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT=rootSTARROCKS_FE_ARROW_FLIGHT_SQL_PORT: (Optional) Arrow Flight SQL port of the StarRocks FE service. When set, the server connects using the high-performance Arrow Flight SQL protocol (via ADBC drivers) instead of the standard MySQL protocol. Leave unset to use the default MySQL connection. The host, user, and password are taken from the same connection settings described above.
STARROCKS_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_MCP_OUTPUT_DIR: (Optional) Directory used by read_query when its output_file argument is a relative path. Defaults to ~/.mcp-server-starrocks/output/. The directory is created on demand. Absolute paths passed to output_file (including ~-prefixed paths) bypass this setting. Note: files are written on the machine where the MCP server runs. For Claude Code / Claude Desktop the server runs locally, so files land on your laptop. For remote/http deployments the file lands on the server, not the client.
STARROCKS_CHART_OUTPUT_DIR: (Optional) Directory where query_and_plotly_chart writes interactive HTML charts (when format="html"). Defaults to the system temp directory. The directory is created on demand. Note: like other output files, charts are written on the machine where the MCP server runs.
STARROCKS_CHART_INCLUDE_PLOTLYJS: (Optional) Controls how plotly.js is bundled into HTML charts. cdn (default) keeps files small but needs network access when viewing; inline/true embeds the full library for offline use; directory and false are also accepted (passed through to Plotly's write_html).
STARROCKS_CHART_DEFAULT_FORMAT: (Optional) Default output format for query_and_plotly_chart when the format argument is omitted. One of json, png, jpeg (default), or html. Set to html to always write an interactive chart file to STARROCKS_CHART_OUTPUT_DIR (with an inline PNG preview) without passing format on every call. Invalid values fall back to jpeg with a warning.
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.
These variables control TLS for the connection. When none of them are set, the underlying mysql.connector keeps its default behavior (ssl-mode=PREFERRED): the connection is encrypted if the server supports TLS, but the server certificate is not verified. For real security, provide a CA certificate and enable verification.
STARROCKS_SSL_DISABLED: (Optional) Set to true to force-disable TLS. Overrides all other SSL settings. Defaults to false.
STARROCKS_SSL_CA: (Optional) Path to the CA certificate (PEM) used to verify the StarRocks server certificate.
STARROCKS_SSL_CERT: (Optional) Path to the client certificate (PEM) for mutual TLS (mTLS).
STARROCKS_SSL_KEY: (Optional) Path to the client private key (PEM) for mutual TLS (mTLS).
STARROCKS_SSL_VERIFY_CERT: (Optional) Set to true to verify the server certificate against the CA. Defaults to false.
STARROCKS_SSL_VERIFY_IDENTITY: (Optional) Set to true to also verify that the server hostname matches the certificate. Defaults to false.
STARROCKS_TLS_VERSIONS: (Optional) Comma-separated list of allowed TLS versions, e.g. TLSv1.2,TLSv1.3.
Example (verify the server against a CA certificate):
"env": {
"STARROCKS_HOST": "your-fe-host",
"STARROCKS_PORT": "9030",
"STARROCKS_USER": "root",
"STARROCKS_PASSWORD": "your-password",
"STARROCKS_SSL_CA": "/path/to/ca.pem",
"STARROCKS_SSL_VERIFY_CERT": "true",
"STARROCKS_SSL_VERIFY_IDENTITY": "true"
}For the high-performance Arrow Flight SQL connection (enabled via STARROCKS_FE_ARROW_FLIGHT_SQL_PORT), TLS is controlled separately:
STARROCKS_FE_ARROW_FLIGHT_SQL_USE_TLS: (Optional) Set to true to use grpc+tls:// instead of plaintext grpc://. When enabled, STARROCKS_SSL_CA is used as the TLS root certificate and STARROCKS_SSL_VERIFY_CERT=false (default) skips server certificate verification.
Security note: avoid storing plaintext passwords directly in
mcp.json. Prefer injectingSTARROCKS_PASSWORD(and certificate paths) from a secrets manager or environment, and never commit credentials to version control.
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
Description: Execute a SELECT query or other commands that return a ResultSet (e.g., SHOW, DESCRIBE). Optionally write the full result to a local file instead of returning it inline — useful for results too large to fit in the model context.
Input:
{
"query": "SQL query string",
"db": "database name (optional, uses default database if not specified)",
"output_file": "optional path; if set, writes the full result to disk and returns only a summary + small preview. Relative paths resolve against STARROCKS_MCP_OUTPUT_DIR (default: ~/.mcp-server-starrocks/output/); absolute paths and ~ are used as-is",
"output_format": "optional: csv | tsv | json | jsonl. If omitted, inferred from output_file extension (.csv/.tsv/.json/.jsonl/.ndjson); defaults to csv"
}Output: Without output_file, text content containing the query results in CSV-like format with a header row and row count summary. With output_file, a short summary including the resolved absolute path, byte count, and row count, plus a small preview. Returns an error message on failure.
write_query
Description: Execute a DDL (CREATE, ALTER, DROP), DML (INSERT, UPDATE, DELETE), or other StarRocks command that does not return a ResultSet.
Input:
{
"query": "SQL command string",
"db": "database name (optional, uses default database if not specified)"
}Output: Text content confirming success (e.g., "Query OK, X rows affected") or reporting an error. Changes are committed automatically on success.
analyze_query
Description: Analyze a query and get analyze result using query profile or explain analyze.
Input:
{
"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)"
}Output: Text content containing the query analysis results. Uses ANALYZE PROFILE FROM if uuid is provided, otherwise uses EXPLAIN ANALYZE if sql is provided.
top_hot_tables
Description: Get top hot tables by audit-log visit count. It joins information_schema.tables with starrocks_audit_db__.starrocks_audit_tbl__, excludes root and SHOW statements, matches audit SQL text against table names, and orders by visit_count descending.
Input:
{
"db": "optional database/schema filter",
"table": "optional table name substring filter",
"min_start_time_ms": 1704067200000,
"max_start_time_ms": 1704153600000,
"top_n": 20
}Output: Text summary plus structured content containing ranked rows with db, table, and visit_count.
top_bad_tables
Description: Get top bad tables by table health score, following Star Management Studio's top-bad-tables logic. It reuses the table-health calculation based on information_schema.be_tablets and information_schema.partitions_meta, filters out system schemas, orders by table_health_score ascending, and returns the lowest-scoring tables.
Input:
{
"db": "optional database/schema filter",
"table": "optional table name substring filter",
"top_n": 20
}Output: Text summary plus structured content containing ranked rows with table health fields such as db, table, tablet_num, replica_score, tablet_score, and table_health_score.
query_and_plotly_chart
Description: Executes a SQL query, loads the results into a Pandas DataFrame, and generates a Plotly chart using a provided Python expression. Designed for visualization in supporting UIs.
Input:
{
"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)"
}Output: A list containing:
TextContent: A text representation of the DataFrame and a note that the chart is for UI display.
ImageContent: The generated Plotly chart encoded as a base64 PNG image (image/png). Returns text error message on failure or if the query yields no data.
table_overview
Description: Get an overview of a specific table: columns (from DESCRIBE), total row count, and sample rows (LIMIT 3). Uses an in-memory cache unless refresh is true.
Input:
{
"table": "Table name, optionally prefixed with database name (e.g., 'db_name.table_name' or 'table_name'). If database is omitted, uses STARROCKS_DB environment variable if set.",
"refresh": false // Optional, boolean. Set to true to bypass the cache. Defaults to false.
}Output: Text content containing the formatted overview (columns, row count, sample data) or an error message. Cached results include previous errors if applicable.
db_overview
Description: Get an overview (columns, row count, sample rows) for all tables within a specified database. Uses the table-level cache for each table unless refresh is true.
Input:
{
"db": "database_name", // Optional if default database is set.
"refresh": false // Optional, boolean. Set to true to bypass the cache for all tables in the DB. Defaults to false.
}Output: Text content containing concatenated overviews for all tables found in the database, separated by headers. Returns an error message if the database cannot be accessed or contains no tables.
starrocks:///databases
Description: Lists all databases accessible to the configured user.
Equivalent Query: SHOW DATABASES
MIME Type: text/plain
starrocks:///{db}/{table}/schema
Description: Gets the schema definition of a specific table.
Equivalent Query: SHOW CREATE TABLE {db}.{table}
MIME Type: text/plain
starrocks:///{db}/tables
Description: Lists all tables within a specific database.
Equivalent Query: SHOW TABLES FROM {db}
MIME Type: text/plain
proc:///{+path}
Description: Accesses StarRocks internal system information, similar to Linux /proc. The path parameter specifies the desired information node.
Equivalent Query: SHOW PROC '/{path}'
MIME Type: text/plain
Common Paths:
/frontends - Information about FE nodes.
/backends - Information about BE nodes (for non-cloud native deployments).
/compute_nodes - Information about CN nodes (for cloud native deployments).
/dbs - Information about databases.
/dbs/<DB_ID> - Information about a specific database by ID.
/dbs/<DB_ID>/<TABLE_ID> - Information about a specific table by ID.
/dbs/<DB_ID>/<TABLE_ID>/partitions - Partition information for a table.
/transactions - Transaction information grouped by database.
/transactions/<DB_ID> - Transaction information for a specific database ID.
/transactions/<DB_ID>/running - Running transactions for a database ID.
/transactions/<DB_ID>/finished - Finished transactions for a database ID.
/jobs - Information about asynchronous jobs (Schema Change, Rollup, etc.).
/statistic - Statistics for each database.
/tasks - Information about agent tasks.
/cluster_balance - Load balance status information.
/routine_loads - Information about Routine Load jobs.
/colocation_group - Information about Colocation Join groups.
/catalog - Information about configured catalogs (e.g., Hive, Iceberg).
None defined by this server.
The table_overview and db_overview tools utilize an in-memory cache to store the generated overview text.
The cache key is a tuple of (database_name, table_name).
When table_overview is called, it checks the cache first. If a result exists and the refresh parameter is false (default), the cached result is returned immediately. Otherwise, it fetches the data from StarRocks, stores it in the cache, and then returns it.
When db_overview is called, it lists all tables in the database and then attempts to retrieve the overview for each table using the same caching logic as table_overview (checking cache first, fetching if needed and refresh is false or cache miss). If refresh is true for db_overview, it forces a refresh for all tables in that database.
The STARROCKS_OVERVIEW_LIMIT environment variable provides a soft target for the maximum length of the overview string generated per table when populating the cache, helping to manage memory usage.
Cached results, including any error messages encountered during the original fetch, are stored and returned on subsequent cache hits.
After starting mcp server, you can use inspector to debug:
npx @modelcontextprotocol/inspector
Analyze a query and get analyze result using query profile. Use set_session_db to set a per-session default database
| Name | Required | Description | Default |
|---|---|---|---|
| db | No | database | |
| sql | No | Query SQL | |
| uuid | No | Query ID, a string composed of 32 hexadecimal digits formatted as 8-4-4-4-12 |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions 'using query profile' but does not disclose whether the tool is read-only, requires authentication, has side effects, or what state (e.g., query must be previously executed) is needed. The behavioral traits are minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose, and includes a concise usage hint. Every sentence adds value without unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the moderate complexity (3 parameters), the description covers the basic purpose and provides a hint about the database parameter. However, it does not clarify the difference between analyzing by SQL vs. UUID, or that the query may need to have been executed first. It is adequate but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing baseline parameter descriptions. The description adds value by explaining that 'set_session_db' can set a per-session default database, indirectly clarifying that the 'db' parameter may be omitted if a default is set. This goes beyond the schema's simple 'database' label.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('analyze a query') and the resource ('query'), and mentions using 'query profile', which indicates the tool's specific function. However, the phrasing 'get analyze result' is slightly redundant, and it doesn't clearly distinguish from sibling tools like 'db_summary' or 'read_query'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a hint to use 'set_session_db' for setting a default database, but provides no guidance on when to use this tool versus alternatives (e.g., 'read_query' or 'query_and_plotly_chart'). There is no mention of prerequisites, exclusions, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a query to get it's query dump and profile, output very large, need special tools to do further processing
| Name | Required | Description | Default |
|---|---|---|---|
| db | No | database | |
| query | Yes | query to execute |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the output is very large and needs special tools, which is useful. However, it does not mention other behavioral traits like destructiveness, permissions, or side effects, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action. It is concise and to the point, though a bit more structure could improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 parameters, no output schema, and no nested objects, the description provides adequate context but does not explain what 'query dump' and 'profile' entail or the return format. It is minimally complete for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both parameters have descriptions: 'database' and 'query to execute'). The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Run a query to get it's query dump and profile', which clearly identifies the verb (run) and resource (query dump and profile). It also mentions the output is very large, adding context. However, it does not differentiate from sibling tools like 'query_and_plotly_chart' or 'read_query'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by stating 'need special tools to do further processing', suggesting this tool is for large outputs requiring post-processing. However, it does not explicitly state when to use this tool versus alternatives, nor provide conditions to avoid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Quickly get summary of a database with tables' schema and size information. Use set_session_db to set a per-session default database
| Name | Required | Description | Default |
|---|---|---|---|
| db | No | Database name. Optional: uses current database by default. | |
| limit | No | Output length limit in characters. Defaults to 10000. Higher values show more tables and details. | |
| refresh | No | Set to true to force refresh, ignoring cache. Defaults to false. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided; the description does not disclose if the tool is read-only, cached, or has side effects. It mentions the refresh parameter but does not explain caching behavior in text, leaving agents without key safety cues.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with an additional useful hint. It is front-loaded and contains no filler, efficiently conveying purpose and context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters and no annotations, the description covers the main use case but falls short on behavioral transparency. The presence of an output schema reduces the need to describe return values. Overall adequate but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all parameters. The description adds some value by linking the 'db' parameter to set_session_db, but does not significantly expand on parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a database summary including table schema and size, with a specific verb and resource. It distinguishes from siblings by mentioning set_session_db for default database context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use (quickly get summary) and references set_session_db for setting a default database. However, it does not explicitly state when not to use or compare to siblings like read_query or table_overview.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| db | No | database | |
| query | Yes | SQL query to execute | |
| format | No | chart output format, json|png|jpeg | jpeg |
| plotly_expr | Yes | a one function call expression, with 2 vars binded: `px` as `import plotly.express as px`, and `df` as dataframe generated by query `plotly_expr` example: `px.scatter(df, x="sepal_width", y="sepal_length", color="species", marginal_y="violin", marginal_x="box", trendline="ols", template="simple_white")` |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It explains the two-step process (query then chart) but does not mention side effects, errors, rate limits, or output format details. The description is simple but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, the first clearly stating the main function. The second sentence provides a related tip but is somewhat tangential. It is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is fairly complete for a combined query-chart tool. It explains the process and mentions a prerequisite. However, it lacks details on output format or error handling, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions, so baseline is 3. The description adds context about the overall workflow but does not elaborate on individual parameters beyond the schema. The mention of set_session_db is peripheral.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it uses SQL query to extract data and then generates a chart with plotly_expr. It distinguishes from siblings like read_query (which only returns data) by explicitly mentioning chart generation. However, it could be more precise by contrasting with other query tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions using set_session_db to set a default database, which is helpful but does not provide guidance on when to use this tool over its siblings (e.g., read_query for data only, analyze_query for analysis). No explicit exclusions or alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| db | No | database | |
| query | Yes | SQL query to execute | |
| output_file | No | If set, write the full result to this file and return only a summary + small preview inline. Relative paths resolve against STARROCKS_MCP_OUTPUT_DIR (default: ~/.mcp-server-starrocks/output/). Absolute paths (and ~) are used as-is. Format is inferred from the file extension (.csv, .tsv, .json, .jsonl, .ndjson) unless output_format is given. NOTE: the file is written on the server's filesystem, which may not be the client machine in remote/http deployments. | |
| output_format | No | Override file format: csv|tsv|json|jsonl. If omitted, inferred from output_file extension; defaults to csv. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavioral traits. It explains the output_file feature and notes that files are written on the server's filesystem, which is important for remote deployments. However, it does not explicitly state that the tool is read-only or discuss error handling or authentication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with the purpose stated first. It includes two sentences plus a minor note, and every part adds value. The only flaw is an extra period after 'inline'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks details about the return structure when output_file is not used. It mentions returning 'inline' but does not specify the format or content (e.g., rows, columns). Given there is no output schema, this information is crucial for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds significant value beyond the schema for output_file and output_format, explaining path resolution, environment variables, and format inference. For db, it adds no extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Execute a SELECT query or commands that return a ResultSet', which provides a specific verb and resource. It distinguishes this tool from siblings like write_query and analyze_query by focusing on read-only queries that produce a result set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., write_query for modifications, analyze_query for explaining). The only instruction is to use set_session_db for default database, which is a side note, not a usage guideline for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| db | No | Database name to set as the per-session default. Empty/null clears the override. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden. It discloses that setting affects subsequent calls without explicit db argument, clarifies clearing behavior, and states the return value. No behavioral contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no redundant words. Every sentence adds critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and no annotations, the description is fully complete. It explains purpose, usage, parameter semantics, and return value. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by explaining that empty string or null clears the override, which is not explicitly in the schema. It clarifies the parameter's effect beyond the bare description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets or clears the default database for the MCP session, using specific verbs ('set', 'clear', 'fall back'). It distinguishes from sibling query tools by focusing on session state management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use (set default) and how to clear (empty/null). While it doesn't explicitly state when not to use or list alternatives, the context of sibling tools makes the usage clear. The guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | Table name, optionally prefixed with database name (e.g., 'db_name.table_name'). If database is omitted, uses the default database. | |
| refresh | No | Set to true to force refresh, ignoring cache. Defaults to false. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses caching behavior and refresh option, which is important for understanding tool behavior. No destructive actions are implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. First sentence clearly states the tool's action and output, second provides important context about caching and database setup. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (2 params, output schema exists), the description covers key aspects: output components, caching, default database. Minor omission like error behavior or limit on sample rows is compensated by output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description does not add semantic meaning beyond the schema descriptions. The parameter details are fully covered by the schema, so description adds no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it provides an overview of a table including columns, sample rows, and row count. However, it does not explicitly differentiate from sibling tools like read_query or analyze_query, which are for querying rather than generating a summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context on caching and default database setup via set_session_db, but lacks explicit guidance on when to use this tool versus alternatives (e.g., read_query for raw data).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| db | No | database | |
| query | Yes | SQL to execute |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description covers non-ResultSet nature but lacks details on side effects, permissions, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with core purpose, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing output schema; description doesn't specify return format or error handling, but purpose and parameters are adequately covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters; description adds value by suggesting set_session_db for default database, enhancing understanding of db parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it executes DDL/DML commands without ResultSet, distinguishing it from sibling tools like read_query which returns results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions using set_session_db for default database but does not explicitly state when to use vs alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct function: query execution, analysis, chart generation, schema summary, etc. There is slight overlap between read_query and query_and_plotly_chart, but their outputs differ (raw data vs chart), and descriptions clarify the distinction. No major confusion.
Tool names follow no consistent pattern: some are verb_noun (e.g., read_query), some are noun_verb (e.g., db_summary), some include conjunctions (query_and_plotly_chart), and verbs vary (analyze, collect, set, write). This inconsistency may confuse an agent trying to infer tool purposes from naming.
With 8 tools, the server is well-scoped for a database MCP server covering querying, analysis, schema browsing, and charting. Each tool serves a clear purpose without being excessive or minimal.
The tool set covers core database interactions: query (read and write), analysis, schema overview, and charting. A minor gap is the absence of a tool to list all databases, but db_summary and set_session_db partially address this. Overall, the surface is reasonably complete for the stated purpose.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Ask data questions in natural language. Get SQL, insights, and charts from your databases.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
Ask business questions in plain English. Get instant answers from your database, no SQL needed.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/StarRocks/mcp-server-starrocks'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
