Skip to main content
Glama
StarRocks MCP Server

StarRocks MCP Server

Official
by StarRocks

StarRocks 공식 MCP 서버

StarRocks MCP 서버는 AI 어시스턴트와 StarRocks 데이터베이스를 연결하는 다리 역할을 합니다. 복잡한 클라이언트 측 설정 없이도 SQL 직접 실행, 데이터베이스 탐색, 차트를 통한 데이터 시각화, 그리고 상세한 스키마/데이터 개요 검색이 가능합니다.

특징

  • 직접 SQL 실행: SELECT 쿼리( read_query ) 및 DDL/DML 명령( write_query )을 실행합니다.

  • 데이터베이스 탐색: 데이터베이스와 테이블을 나열하고, 테이블 스키마를 검색합니다( starrocks:// resources).

  • 시스템 정보: proc:// 리소스 경로를 통해 내부 StarRocks 메트릭과 상태에 액세스합니다.

  • 자세한 개요: 열 정의, 행 수, 샘플 데이터를 포함하여 테이블( table_overview )이나 전체 데이터베이스( db_overview )에 대한 포괄적인 요약을 얻습니다.

  • 데이터 시각화: 쿼리를 실행하고 결과에서 바로 Plotly 차트를 생성합니다( query_and_plotly_chart ).

  • 지능형 캐싱: 테이블 및 데이터베이스 개요를 메모리에 캐시하여 반복 요청 속도를 높입니다. 필요 시 캐시를 우회할 수 있습니다.

  • 유연한 구성: 환경 변수를 통해 연결 세부 정보와 동작을 설정합니다.

Related MCP server: mcp-server-starrocks

구성

MCP 서버는 일반적으로 MCP 호스트를 통해 실행됩니다. StarRocks MCP 서버 프로세스를 시작하는 방법을 지정하는 구성이 호스트로 전달됩니다.

설치된 패키지에서 uv 사용:

지엑스피1

로컬 디렉토리에서 uv 사용(개발용):

{
  "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",
        "STARROCKS_OVERVIEW_LIMIT": "default 20000"
      }
    }
  }
}

환경 변수:

  • STARROCKS_HOST : (선택 사항) StarRocks FE 서비스의 호스트 이름 또는 IP 주소입니다. 기본값은 localhost 입니다.

  • STARROCKS_PORT : (선택 사항) StarRocks FE 서비스의 MySQL 프로토콜 포트입니다. 기본값은 9030 입니다.

  • STARROCKS_USER : (선택 사항) StarRocks 사용자 이름입니다. 기본값은 root 입니다.

  • STARROCKS_PASSWORD : (선택 사항) StarRocks 비밀번호입니다. 기본값은 빈 문자열입니다.

  • STARROCKS_DB : (선택 사항) 도구 인수 또는 리소스 URI에 지정되지 않은 경우 사용할 기본 데이터베이스입니다. 설정된 경우 연결 시 이 데이터베이스를 USE 하려고 시도합니다. table_overview 및 db_overview 와 같은 도구는 인수에 데이터베이스 부분이 생략된 경우 이 데이터베이스를 사용합니다. 기본값은 비어 있음(기본 데이터베이스 없음)입니다.

  • STARROCKS_OVERVIEW_LIMIT : (선택 사항) 개요 도구( table_overview , db_overview )에서 캐시를 채우기 위해 데이터를 가져올 때 생성되는 총 텍스트의 대략적인 문자 수 제한입니다. 이 설정은 매우 큰 스키마나 여러 테이블에서 과도한 메모리 사용을 방지하는 데 도움이 됩니다. 기본값은 20000 입니다.

구성 요소

도구

  • read_query

    • 설명: ResultSet을 반환하는 SELECT 쿼리나 다른 명령(예: SHOW , DESCRIBE )을 실행합니다.

    • 입력: { "query": "SQL query string" }

    • 출력: 헤더 행과 행 개수 요약을 포함한 CSV 형식의 쿼리 결과를 담은 텍스트 콘텐츠입니다. 실패 시 오류 메시지를 반환합니다.

  • write_query

    • 설명: ResultSet을 반환하지 않는 DDL( CREATE , ALTER , DROP ), DML( INSERT , UPDATE , DELETE ) 또는 기타 StarRocks 명령을 실행합니다.

    • 입력: { "query": "SQL command string" }

    • 출력: 성공을 확인하는 텍스트 콘텐츠(예: "쿼리 성공, X개 행 영향 받음") 또는 오류를 보고합니다. 성공 시 변경 사항이 자동으로 커밋됩니다.

  • query_and_plotly_chart

    • 설명: SQL 쿼리를 실행하고, 결과를 Pandas DataFrame에 로드하고, 제공된 Python 표현식을 사용하여 Plotly 차트를 생성합니다. 지원되는 UI에서 시각화하도록 설계되었습니다.

    • 입력:

      {
        "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\")'"
      }
    • 출력: 다음이 포함된 목록:

      1. TextContent : DataFrame의 텍스트 표현과 차트가 UI 표시용이라는 메모입니다.

      2. ImageContent : 생성된 Plotly 차트를 base64 PNG 이미지( image/png )로 인코딩합니다. 실패하거나 쿼리에서 데이터가 반환되지 않으면 텍스트 오류 메시지를 반환합니다.

  • table_overview

    • 설명: 특정 테이블의 개요를 가져옵니다(열( DESCRIBE 에서 가져온 값), 총 행 수, 샘플 행( LIMIT 3 )). refresh 가 true가 아니면 메모리 내 캐시를 사용합니다.

    • 입력:

      {
        "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.
      }
    • 출력: 서식이 적용된 개요(열, 행 개수, 샘플 데이터) 또는 오류 메시지를 포함하는 텍스트 콘텐츠입니다. 캐시된 결과에는 이전 오류가 포함된 경우 포함됩니다.

  • db_overview

    • 설명: 지정된 데이터베이스 내 모든 테이블에 대한 개요(열, 행 수, 샘플 행)를 가져옵니다. refresh 참이 아닌 경우 각 테이블에 대해 테이블 수준 캐시를 사용합니다.

    • 입력:

      {
        "db": "database_name", // Optional if STARROCKS_DB env var is set.
        "refresh": false // Optional, boolean. Set to true to bypass the cache for all tables in the DB. Defaults to false.
      }
    • 출력: 데이터베이스에서 발견된 모든 테이블에 대한 연결 개요를 헤더로 구분하여 포함하는 텍스트 콘텐츠입니다. 데이터베이스에 액세스할 수 없거나 데이터베이스 테이블에 테이블이 없는 경우 오류 메시지를 반환합니다.

자원

직접 자원

  • starrocks:///databases

    • 설명: 구성된 사용자가 액세스할 수 있는 모든 데이터베이스를 나열합니다.

    • 동등한 쿼리: SHOW DATABASES

    • MIME 유형: text/plain

리소스 템플릿

  • starrocks:///{db}/{table}/schema

    • 설명: 특정 테이블의 스키마 정의를 가져옵니다.

    • 동등한 쿼리: SHOW CREATE TABLE {db}.{table}

    • MIME 유형: text/plain

  • starrocks:///{db}/tables

    • 설명: 특정 데이터베이스 내의 모든 테이블을 나열합니다.

    • 동등한 쿼리: SHOW TABLES FROM {db}

    • MIME 유형: text/plain

  • proc:///{+path}

    • 설명: Linux의 /proc 명령과 유사하게 StarRocks 내부 시스템 정보에 접근합니다. path 매개변수는 원하는 정보 노드를 지정합니다.

    • 동등한 쿼리: SHOW PROC '/{path}'

    • MIME 유형: text/plain

    • 일반적인 경로:

      • /frontends - FE 노드에 대한 정보.

      • /backends - BE 노드에 대한 정보(클라우드 네이티브가 아닌 배포의 경우).

      • /compute_nodes - CN 노드에 대한 정보(클라우드 네이티브 배포용).

      • /dbs - 데이터베이스에 대한 정보.

      • /dbs/<DB_ID> - ID별 특정 데이터베이스에 대한 정보.

      • /dbs/<DB_ID>/<TABLE_ID> - ID별 특정 테이블에 대한 정보.

      • /dbs/<DB_ID>/<TABLE_ID>/partitions - 테이블에 대한 파티션 정보.

      • /transactions - 데이터베이스별로 그룹화된 거래 정보입니다.

      • /transactions/<DB_ID> - 특정 데이터베이스 ID에 대한 트랜잭션 정보.

      • /transactions/<DB_ID>/running - 데이터베이스 ID에 대한 트랜잭션 실행.

      • /transactions/<DB_ID>/finished - 데이터베이스 ID에 대한 완료된 트랜잭션.

      • /jobs - 비동기 작업(스키마 변경, 롤업 등)에 대한 정보입니다.

      • /statistic - 각 데이터베이스에 대한 통계.

      • /tasks - 에이전트 작업에 대한 정보.

      • /cluster_balance - 부하 분산 상태 정보.

      • /routine_loads - 루틴 로드 작업에 대한 정보입니다.

      • /colocation_group - Colocation Join 그룹에 대한 정보입니다.

      • /catalog - 구성된 카탈로그(예: Hive, Iceberg)에 대한 정보입니다.

프롬프트

이 서버에서는 아무것도 정의되지 않았습니다.

캐싱 동작

  • table_overview 및 db_overview 도구는 메모리 내 캐시를 활용하여 생성된 개요 텍스트를 저장합니다.

  • 캐시 키는 (database_name, table_name) 의 튜플입니다.

  • table_overview 호출되면 먼저 캐시를 확인합니다. 결과가 존재하고 refresh 매개변수가 false (기본값)이면 캐시된 결과가 즉시 반환됩니다. 그렇지 않으면 StarRocks에서 데이터를 가져와 캐시에 저장한 다음 반환합니다.

  • db_overview 호출되면 데이터베이스의 모든 테이블을 나열한 다음, table_overview 와 동일한 캐싱 로직(먼저 캐시를 확인하고, 필요한 경우 가져오며, refresh 가 false 이거나 캐시 미스)을 사용하여 각 테이블 의 개요를 검색합니다. db_overview 의 refresh 가 true 이면 해당 데이터베이스의 모든 테이블을 강제로 새로 고칩니다.

  • STARROCKS_OVERVIEW_LIMIT 환경 변수는 캐시를 채울 때 테이블당 생성되는 개요 문자열의 최대 길이에 대한 소프트 목표를 제공하여 메모리 사용량을 관리하는 데 도움이 됩니다.

  • 원래 페치 중에 발생한 오류 메시지를 포함한 캐시된 결과는 저장되어 후속 캐시 히트 시 반환됩니다.

데모

MCP 데모 이미지

Available Tools

8 tools
analyze_queryB

Analyze a query and get analyze result using query profile. Use set_session_db to set a per-session default database

Inputs: db, sql, uuid. Returns: result

collect_query_dump_and_profileB

Run a query to get it's query dump and profile, output very large, need special tools to do further processing

Inputs: query (required), db.

db_summaryA

Quickly get summary of a database with tables' schema and size information. Use set_session_db to set a per-session default database

Inputs: db, limit, refresh. Returns: result

query_and_plotly_chartB

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

Inputs: query (required), plotly_expr (required), db, format.

read_queryA

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

Inputs: query (required), db, output_file, output_format.

set_session_dbA

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.

Inputs: db. Returns: result

table_overviewA

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

Inputs: table (required), refresh. Returns: result

write_queryA

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

Inputs: query (required), db.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency2/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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.

    Maintenance

    ActivityStale
    ResponsivenessMixed handling

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to connect to StarRocks databases for direct SQL execution, schema and database exploration, system metrics access, and Plotly chart generation. It also provides cached table and database overviews.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to query and explore StarRocks databases, inspect schemas, metrics, and sample data, and generate Plotly charts from query results without complex client-side setup.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Acts as a bridge between AI assistants and StarRocks databases, enabling direct SQL execution, listing databases and tables, retrieving table schemas and system metrics, generating data overviews with sample rows, and rendering query results as Plotly charts — all without complex client-side setup.
      -