StarRocks Database Connector MCP Server

DatabasesPython

Connect to and interact with StarRocks databases directly from AI assistants

Available Tools

read_query

Execute a SELECT query or other commands that return a ResultSet (e.g., SHOW, DESCRIBE)

query

write_query

Execute a DDL (CREATE, ALTER, DROP), DML (INSERT, UPDATE, DELETE), or other StarRocks command that does not return a ResultSet

query

query_and_plotly_chart

Executes a SQL query, loads the results into a Pandas DataFrame, and generates a Plotly chart using a provided Python expression

queryplotly_expr

table_overview

Get an overview of a specific table: columns, total row count, and sample rows. Uses an in-memory cache unless refresh is true

tablerefresh

db_overview

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

dbrefresh

The StarRocks Database Connector serves as a bridge between AI assistants and StarRocks databases, enabling direct SQL execution, database exploration, and data visualization. It allows users to query data, examine database schemas, generate visual charts, and retrieve comprehensive overviews of tables or entire databases without complex client-side setup. With intelligent caching and flexible configuration options, it streamlines database interactions for both simple queries and complex data analysis tasks.

Overview

The StarRocks Database Connector enables AI assistants to directly interact with StarRocks databases. This connector provides a comprehensive set of capabilities including executing SQL queries, exploring database structures, visualizing data with charts, and retrieving detailed information about tables and databases.

Installation

To install the StarRocks Database Connector, add the following configuration to your AI assistant's settings:

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-server-starrocks",
        "mcp-server-starrocks"
      ],
      "env": {
        "STARROCKS_HOST": "localhost",
        "STARROCKS_PORT": "9030",
        "STARROCKS_USER": "root",
        "STARROCKS_PASSWORD": "",
        "STARROCKS_DB": "",
        "STARROCKS_OVERVIEW_LIMIT": "20000"
      }
    }
  }
}

For development purposes, you can also run it from a local directory:

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mcp-server-starrocks",
        "run",
        "mcp-server-starrocks"
      ],
      "env": {
        "STARROCKS_HOST": "localhost",
        "STARROCKS_PORT": "9030",
        "STARROCKS_USER": "root",
        "STARROCKS_PASSWORD": "",
        "STARROCKS_DB": "",
        "STARROCKS_OVERVIEW_LIMIT": "20000"
      }
    }
  }
}

Configuration

The connector can be configured using the following environment variables:

STARROCKS_HOST: Hostname or IP address of the StarRocks FE service (default: localhost)
STARROCKS_PORT: MySQL protocol port of the StarRocks FE service (default: 9030)
STARROCKS_USER: StarRocks username (default: root)
STARROCKS_PASSWORD: StarRocks password (default: empty string)
STARROCKS_DB: Default database to use if not specified in tool arguments (default: empty)
STARROCKS_OVERVIEW_LIMIT: Character limit for text generated by overview tools (default: 20000)

Usage

Querying Data

You can execute read-only queries using the read_query tool:

read_query({"query": "SELECT * FROM my_database.my_table LIMIT 10"})

For queries that modify data or schema (DDL/DML), use the write_query tool:

write_query({"query": "CREATE TABLE my_database.new_table (id INT, name VARCHAR(100))"})

Database Exploration

To list all databases:

starrocks:///databases

To list all tables in a database:

starrocks:///my_database/tables

To view a table's schema:

starrocks:///my_database/my_table/schema

Table and Database Overviews

For a comprehensive overview of a specific table:

table_overview({"table": "my_database.my_table"})

To get an overview of all tables in a database:

db_overview({"db": "my_database"})

Data Visualization

To generate a chart from query results:

query_and_plotly_chart({
  "query": "SELECT date, sales FROM my_database.sales_data",
  "plotly_expr": "px.line(df, x='date', y='sales', title='Sales Over Time')"
})

Caching

The connector implements intelligent caching for table and database overviews to improve performance. To bypass the cache and fetch fresh data, set the refresh parameter to true:

table_overview({"table": "my_database.my_table", "refresh": true})

Security Considerations

The connector validates all inputs, particularly the plotly_expr parameter, to enhance security. It only allows access to the data and operations permitted by the configured StarRocks user credentials.