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

Additional Configuration

• 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_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.

Components

Tools

• read_query

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

    {
      "query": "SQL query string",
      "db": "database name (optional, uses default database if not specified)"
    }
    

  • Output: Text content containing the query results in a CSV-like format, including a header row and a row count summary. 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.

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