StarRocks MCP Server

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 ).
• 지능형 캐싱: 테이블 및 데이터베이스 개요를 메모리에 캐시하여 반복 요청 속도를 높입니다. 필요 시 캐시를 우회할 수 있습니다.
• 유연한 구성: 환경 변수를 통해 연결 세부 정보와 동작을 설정합니다.

구성

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

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

지엑스피1

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

환경 변수:

• 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 환경 변수는 캐시를 채울 때 테이블당 생성되는 개요 문자열의 최대 길이에 대한 소프트 목표를 제공하여 메모리 사용량을 관리하는 데 도움이 됩니다.
• 원래 페치 중에 발생한 오류 메시지를 포함한 캐시된 결과는 저장되어 후속 캐시 히트 시 반환됩니다.

데모