StarRocks Official MCP Server

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

# 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 uv

See the official uv installation guide for other options. After installing, verify it is on your PATH:

uv --version

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:

# 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 --help

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):

$ STARROCKS_URL=root:@localhost:9030 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 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 --test

• The 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:

Connection Configuration

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 -w

Use 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=root

Additional Configuration

• STARROCKS_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 passwor