StarRocks MCP Server

공식

StarRocks와 상호작용

문서

StarRocks 공식 MCP 서버

StarRocks MCP 서버는 AI 어시스턴트와 StarRocks 데이터베이스 간의 브릿지 역할을 합니다. 복잡한 클라이언트 측 설정 없이 직접 SQL 실행, 데이터베이스 탐색, 차트를 통한 데이터 시각화, 상세한 스키마/데이터 개요 조회를 가능하게 합니다.

기능

직접 SQL 실행: SELECT 쿼리(read_query) 및 DDL/DML 명령(write_query)을 실행합니다.
데이터베이스 탐색: 데이터베이스 및 테이블 목록을 조회하고, 테이블 스키마(starrocks:// 리소스)를 가져옵니다.
시스템 정보: proc:// 리소스 경로를 통해 내부 StarRocks 메트릭 및 상태에 접근합니다.
상세 개요: 열 정의, 행 수, 샘플 데이터를 포함하여 테이블(table_overview) 또는 전체 데이터베이스(db_overview)에 대한 포괄적인 요약 정보를 가져옵니다.
데이터 시각화: 쿼리를 실행하고 결과에서 직접 Plotly 차트를 생성합니다(query_and_plotly_chart).
지능형 캐싱: 테이블 및 데이터베이스 개요가 메모리에 캐시되어 반복 요청 속도를 높입니다. 필요 시 캐시를 우회할 수 있습니다.
유연한 구성: 환경 변수를 통해 연결 세부 정보 및 동작을 설정합니다.

사전 요구 사항

Python 3.11 이상.
접근 가능한 StarRocks 클러스터(FE 서비스). 기본적으로 서버는 MySQL 프로토콜을 통해 localhost:9030에 연결합니다.
uv — Astral에서 제공하는 빠른 Python 패키지 및 프로젝트 관리자(pip + virtualenv의 현대적인 대체 도구). 이 프로젝트는 uv을 사용하여 의존성을 해결하고, 가상 환경을 생성하며, 서버를 시작합니다. 이 README 전체에서 사용되는 uv run 명령은 처음 사용 시 자동으로 격리된 환경을 생성하고 필요한 의존성을 설치하므로, 수동으로 pip install 단계를 수행할 필요가 없습니다.

`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

다른 옵션은 공식 uv 설치 가이드를 참조하세요. 설치 후, PATH에 있는지 확인하세요:

uv --version

설치

일반적으로 패키지를 수동으로 설치할 필요는 없습니다 — MCP 호스트가 uv을 통해 실행합니다(아래 구성 참조). uv이 필요 시 패키지와 의존성을 가져옵니다.

테스트 또는 개발을 위해 직접 실행하려면:

# 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

구성

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

Streamable HTTP 사용 (권장):

Streamable HTTP 모드로 서버를 시작하려면:

먼저 StarRocks 연결이 정상인지 테스트합니다(9030은 HTTP 서버 포트가 아닌 StarRocks MySQL 프로토콜 포트입니다):

$ STARROCKS_URL=root:@localhost:9030 uv run mcp-server-starrocks --test

서버 시작:

uv run mcp-server-starrocks --mode streamable-http --port 8000

그런 다음 MCP를 다음과 같이 구성합니다:

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

설치된 패키지와 함께 uv 사용 (개별 환경 변수):

{
  "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"
      }
    }
  }
}

설치된 패키지와 함께 uv 사용 (연결 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"
      }
    }
  }
}

로컬 디렉터리와 함께 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"
      }
    }
  }
}

로컬 디렉터리 및 연결 URL과 함께 uv 사용:

{
  "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"
      }
    }
  }
}

명령줄 인수:

서버는 다음 명령줄 인수를 지원합니다:

uv run mcp-server-starrocks --help

--mode {stdio,sse,http,streamable-http}: 전송 모드 (기본값: stdio 또는 MCP_TRANSPORT_MODE 환경 변수)
--host HOST: HTTP 모드용 서버 호스트 (기본값: localhost)
--port PORT: HTTP 모드용 서버 포트
--test: 기능 검증을 위한 테스트 모드로 실행

예시:

# 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

url 필드는 MCP 서버의 Streamable HTTP 엔드포인트를 가리켜야 합니다 (필요에 따라 호스트/포트 조정).
이 구성을 사용하면 클라이언트는 HTTP POST 요청을 통해 표준 JSON으로 서버와 상호 작용할 수 있습니다. 특별한 SDK가 필요하지 않습니다.
모든 도구 API는 위에서 설명한 대로 표준 JSON을 수락하고 반환합니다.

참고: sse (Server-Sent Events) 모드는 더 이상 사용되지 않으며 유지 관리되지 않습니다. 모든 새로운 통합에는 Streamable HTTP 모드를 사용하십시오.

환경 변수:

연결 구성

개별 환경 변수 또는 단일 연결 URL을 사용하여 StarRocks 연결을 구성할 수 있습니다:

옵션 1: 개별 환경 변수

STARROCKS_HOST: (선택 사항) StarRocks FE 서비스의 호스트 이름 또는 IP 주소. 기본값은 localhost입니다.
STARROCKS_PORT: (선택 사항) StarRocks FE 서비스의 MySQL 프로토콜 포트. 기본값은 9030입니다.
STARROCKS_USER: (선택 사항) StarRocks 사용자 이름. 기본값은 root입니다.
STARROCKS_PASSWORD: (선택 사항) StarRocks 비밀번호. 기본값은 빈 문자열입니다.
STARROCKS_PASSWORD_KEYCHAIN_SERVICE: (선택 사항, macOS 전용) 키체인에서 비밀번호를 읽을 때 사용할 일반 비밀번호 서비스 이름. STARROCKS_PASSWORD 또는 STARROCKS_URL을 통해 명시적인 비밀번호가 제공되지 않은 경우에만 사용됩니다.
STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT: (선택 사항, macOS 전용) 키체인에서 비밀번호를 읽을 때 사용할 일반 비밀번호 계정 이름. 기본값은 확인된 StarRocks 사용자입니다.
STARROCKS_DB: (선택 사항) 도구 인수 또는 리소스 URI에 지정되지 않은 경우 사용할 기본 데이터베이스. 설정되면 연결 시 이 데이터베이스로 USE을 시도합니다. table_overview 및 db_overview과 같은 도구는 인수에서 데이터베이스 부분이 생략된 경우 이를 사용합니다. 기본값은 비어 있습니다(기본 데이터베이스 없음).

옵션 2: 연결 URL (개별 변수보다 우선함)

STARROCKS_URL: (선택 사항) 모든 연결 매개변수를 단일 변수에 포함하는 연결 URL 문자열. 형식: [<schema>://]user:password@host:port/database. 스키마 부분은 선택 사항입니다. 이 변수가 설정되면 개별 STARROCKS_HOST, STARROCKS_PORT, STARROCKS_USER, STARROCKS_PASSWORD 및 STARROCKS_DB 변수보다 우선합니다.

예시:
- root:mypass@localhost:9030/test_db
- mysql://admin:[email protected]:9030/production
- starrocks://user:[email protected]:9030/analytics

비밀번호 우선순위:

STARROCKS_URL에 포함된 비밀번호가 우선하며, user:@host:9030/db와 같은 명시적인 빈 비밀번호도 포함됩니다.
STARROCKS_URL이 비밀번호를 생략한 경우, STARROCKS_PASSWORD이 설정되어 있으면 사용됩니다.
명시적인 비밀번호 소스가 설정되지 않고 STARROCKS_PASSWORD_KEYCHAIN_SERVICE이 구성된 경우, macOS 키체인에서 비밀번호를 읽습니다.

macOS 키체인 예시

비밀번호 저장:

security add-generic-password -U -a root -s mcp-server-starrocks -w 'secret'

저장된 비밀번호 확인:

security find-generic-password -a root -s mcp-server-starrocks -w

이 서버와 함께 사용:

export STARROCKS_URL=root@localhost:9030/test_db
export STARROCKS_PASSWORD_KEYCHAIN_SERVICE=mcp-server-starrocks
export STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT=root

추가 구성

STARROCKS_FE_ARROW_FLIGHT_SQL_PORT: (선택 사항) StarRocks FE 서비스의 Arrow Flight SQL 포트. 설정되면 서버는 표준 MySQL 프로토콜 대신 고성능 Arrow Flight SQL 프로토콜(ADBC 드라이버를 통해)을 사용하여 연결합니다. 기본 MySQL 연결을 사용하려면 설정하지 않은 상태로 둡니다. 호스트, 사용자 및 비밀번호는 위에서 설명한 동일한 연결 설정에서 가져옵니다.
STARROCKS_OVERVIEW_LIMIT: (선택 사항) 캐시를 채우기 위해 데이터를 가져올 때 개요 도구(table_overview, db_overview)가 생성하는 전체 텍스트에 대한 대략적인 문자 제한. 이는 매우 큰 스키마나 많은 테이블에 대한 과도한 메모리 사용을 방지하는 데 도움이 됩니다. 기본값은 20000입니다.
STARROCKS_MCP_OUTPUT_DIR: (선택 사항) read_query의 output_file 인수가 상대 경로일 때 사용되는 디렉터리. 기본값은 ~/.mcp-server-starrocks/output/입니다. 디렉터리는 필요 시 생성됩니다. output_file에 전달된 절대 경로(~ 접두사 경로 포함)는 이 설정을 우회합니다. 참고: 파일은 MCP 서버가 실행되는 머신에 기록됩니다. Claude Code / Claude Desktop의 경우 서버가 로컬에서 실행되므로 파일은 사용자의 노트북에 저장됩니다. 원격/HTTP 배포의 경우 파일은 클라이언트가 아닌 서버에 저장됩니다.
STARROCKS_MYSQL_AUTH_PLUGIN: (선택 사항) StarRocks FE 서비스에 연결할 때 사용할 인증 플러그인을 지정합니다. 예를 들어, StarRocks 배포에서 일반 텍스트 비밀번호 인증이 필요한 경우(특정 LDAP 또는 외부 인증 설정을 사용하는 경우 등) mysql_clear_password로 설정합니다. 환경에서 특별히 요구하는 경우에만 설정하고, 그렇지 않으면 기본 auth_plugin이 사용됩니다.
MCP_TRANSPORT_MODE: (선택 사항) MCP 서버가 서비스를 노출하는 방식을 지정하는 통신 모드. 사용 가능한 옵션:
- stdio (기본값): 표준 입출력을 통해 통신하며, MCP 호스트 호스팅에 적합합니다.
- streamable-http (Streamable HTTP): Streamable HTTP 서버로 시작하여 RESTful API 호출을 지원합니다.
- sse: (더 이상 사용되지 않음, 권장하지 않음) Server-Sent Events (SSE) 스트리밍 모드로 시작하며, 스트리밍 응답이 필요한 시나리오에 적합합니다. 참고: SSE 모드는 더 이상 유지 관리되지 않으며, Streamable HTTP 모드를 일관되게 사용하는 것이 좋습니다.

구성 요소

도구

read_query
- 설명: SELECT 쿼리 또는 ResultSet을 반환하는 기타 명령(예: SHOW, DESCRIBE)을 실행합니다. 선택적으로 전체 결과를 인라인으로 반환하는 대신 로컬 파일에 기록할 수 있으며, 이는 모델 컨텍스트에 맞추기 너무 큰 결과에 유용합니다.
- 입력:
```
{
  "query": "SQL query string",
  "db": "database name (optional, uses default database if not specified)",
  "output_file": "optional path; if set, writes the full result to disk and returns only a summary + small preview. Relative paths resolve against STARROCKS_MCP_OUTPUT_DIR (default: ~/.mcp-server-starrocks/output/); absolute paths and ~ are used as-is",
  "output_format": "optional: csv | tsv | json | jsonl. If omitted, inferred from output_file extension (.csv/.tsv/.json/.jsonl/.ndjson); defaults to csv"
}
```
- 출력: output_file가 없는 경우, 헤더 행과 행 수 요약이 포함된 CSV 유사 형식의 쿼리 결과를 포함하는 텍스트 콘텐츠. output_file가 있는 경우, 확인된 절대 경로, 바이트 수, 행 수 및 작은 미리보기를 포함하는 짧은 요약. 실패 시 오류 메시지를 반환합니다.
write_query
- 설명: DDL(CREATE, ALTER, DROP), DML(INSERT, UPDATE, DELETE) 또는 ResultSet을 반환하지 않는 기타 StarRocks 명령을 실행합니다.
- 입력:
```
{
  "query": "SQL command string",
  "db": "database name (optional, uses default database if not specified)"
}
```
- 출력: 성공을 확인하는 텍스트 콘텐츠(예: "Query OK, X rows affected") 또는 오류 보고. 성공 시 변경 사항이 자동으로 커밋됩니다.
analyze_query
- 설명: 쿼리 프로필 또는 explain analyze를 사용하여 쿼리를 분석하고 분석 결과를 가져옵니다.
- 입력:
```
{
  "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)"
}
```
- 출력: 쿼리 분석 결과를 포함하는 텍스트 콘텐츠. uuid가 제공되면 ANALYZE PROFILE FROM를 사용하고, sql이 제공되면 EXPLAIN ANALYZE을 사용합니다.
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\")'",
  "db": "database name (optional, uses default database if not specified)"
}
```
- 출력: 다음을 포함하는 목록:
  1. TextContent: DataFrame의 텍스트 표현 및 차트가 UI 표시용임을 알리는 메모.
  2. ImageContent: base64 PNG 이미지(image/png)로 인코딩된 생성된 Plotly 차트. 실패하거나 쿼리 결과가 데이터를 반환하지 않으면 텍스트 오류 메시지를 반환합니다.
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이 true가 아닌 한 각 테이블에 대해 테이블 수준 캐시를 사용합니다.
- 입력:
```
{
  "db": "database_name", // Optional if default database 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 - 컬로케이션 조인 그룹에 대한 정보.
  - /catalog - 구성된 카탈로그(예: Hive, Iceberg)에 대한 정보.

프롬프트

이 서버에서 정의된 프롬프트가 없습니다.

캐싱 동작

table_overview 및 db_overview 도구는 생성된 개요 텍스트를 저장하기 위해 인메모리 캐시를 활용합니다.
캐시 키는 (database_name, table_name)의 튜플입니다.
table_overview이 호출되면 먼저 캐시를 확인합니다. 결과가 존재하고 refresh 매개변수가 false (기본값)이면 캐시된 결과가 즉시 반환됩니다. 그렇지 않으면 StarRocks에서 데이터를 가져와 캐시에 저장한 후 반환합니다.
db_overview이 호출되면 데이터베이스의 모든 테이블을 나열한 다음 table_overview과 동일한 캐싱 로직(먼저 캐시 확인, 필요하고 refresh이 false이거나 캐시 미스인 경우 가져오기)을 사용하여 _각 테이블_에 대한 개요를 검색하려고 시도합니다. refresh이 true인 경우 db_overview에 대해 해당 데이터베이스의 모든 테이블에 대한 새로 고침을 강제합니다.
STARROCKS_OVERVIEW_LIMIT 환경 변수는 캐시를 채울 때 테이블당 생성되는 개요 문자열의 최대 길이에 대한 _소프트 목표_를 제공하여 메모리 사용량 관리를 돕습니다.
원래 가져오기 중에 발생한 오류 메시지를 포함하여 캐시된 결과는 저장되며 후속 캐시 히트 시 반환됩니다.

디버그

mcp 서버를 시작한 후 인스펙터를 사용하여 디버그할 수 있습니다:

npx @modelcontextprotocol/inspector

데모

MCP Demo Image