StarRocks MCP Server

chính thức

Tương tác với StarRocks

Tài liệu

Máy chủ MCP Chính thức của StarRocks

Máy chủ StarRocks MCP hoạt động như một cầu nối giữa các trợ lý AI và cơ sở dữ liệu StarRocks. Nó cho phép thực thi SQL trực tiếp, khám phá cơ sở dữ liệu, trực quan hóa dữ liệu qua biểu đồ và truy xuất tổng quan chi tiết về lược đồ/dữ liệu mà không yêu cầu thiết lập phía máy khách phức tạp.

Tính năng

Thực thi SQL Trực tiếp: Chạy các truy vấn SELECT (read_query) và các lệnh DDL/DML (write_query).
Khám phá Cơ sở dữ liệu: Liệt kê cơ sở dữ liệu và bảng, truy xuất lược đồ bảng (tài nguyên starrocks://).
Thông tin Hệ thống: Truy cập các số liệu và trạng thái nội bộ của StarRocks qua đường dẫn tài nguyên proc://.
Tổng quan Chi tiết: Nhận tóm tắt toàn diện về các bảng (table_overview) hoặc toàn bộ cơ sở dữ liệu (db_overview), bao gồm định nghĩa cột, số lượng hàng và dữ liệu mẫu.
Trực quan hóa Dữ liệu: Thực thi truy vấn và tạo biểu đồ Plotly trực tiếp từ kết quả (query_and_plotly_chart).
Bộ nhớ đệm Thông minh: Tổng quan về bảng và cơ sở dữ liệu được lưu vào bộ nhớ đệm để tăng tốc các yêu cầu lặp lại. Có thể bỏ qua bộ nhớ đệm khi cần.
Cấu hình Linh hoạt: Đặt chi tiết kết nối và hành vi qua biến môi trường.

Điều kiện tiên quyết

Python 3.11 trở lên.
Một cụm StarRocks có thể truy cập được (dịch vụ FE). Theo mặc định, máy chủ kết nối tới localhost:9030 qua giao thức MySQL.
uv — một công cụ quản lý gói và dự án Python nhanh (thay thế hiện đại cho pip + virtualenv) từ Astral. Dự án này sử dụng uv để giải quyết các phụ thuộc, tạo môi trường ảo và khởi chạy máy chủ. Các lệnh uv run trong toàn bộ README này tự động tạo một môi trường cách ly và cài đặt các phụ thuộc cần thiết trong lần sử dụng đầu tiên, do đó không cần bước pip install thủ công.

Cài đặt `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

Xem hướng dẫn cài đặt chính thức của uv để biết các tùy chọn khác. Sau khi cài đặt, hãy xác minh nó có trong PATH của bạn:

uv --version

Cài đặt

Bạn thường không cần cài đặt gói thủ công — máy chủ MCP sẽ khởi chạy nó cho bạn qua uv (xem Cấu hình bên dưới). uv tải gói và các phụ thuộc của nó theo yêu cầu.

Để chạy trực tiếp cho mục đích kiểm thử hoặc phát triển:

# 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

Cấu hình

Máy chủ MCP thường được chạy qua một máy chủ MCP. Cấu hình được truyền cho máy chủ, chỉ định cách khởi chạy tiến trình máy chủ StarRocks MCP.

Sử dụng HTTP có thể truyền phát (khuyến nghị):

Để khởi động máy chủ ở chế độ HTTP có thể truyền phát:

Trước tiên, hãy kiểm tra kết nối tới StarRocks ổn định (9030 là cổng giao thức MySQL của StarRocks, không phải cổng máy chủ HTTP):

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

Khởi động máy chủ:

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

Sau đó cấu hình MCP như sau:

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

Sử dụng uv với gói đã cài đặt (biến môi trường riêng lẻ):

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

Sử dụng uv với gói đã cài đặt (URL kết nối):

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": ["run", "--with", "mcp-server-starrocks", "mcp-server-starrocks"],
      "env": {
        "STARROCKS_URL": "root:password@localhost:9030/my_database"
      }
    }
  }
}

Sử dụng uv với thư mục cục bộ (cho phát triển):

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

Sử dụng uv với thư mục cục bộ và URL kết nối:

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

Tham số Dòng lệnh:

Máy chủ hỗ trợ các tham số dòng lệnh sau:

uv run mcp-server-starrocks --help

--mode {stdio,sse,http,streamable-http}: Chế độ truyền tải (mặc định: stdio hoặc biến môi trường MCP_TRANSPORT_MODE)
--host HOST: Máy chủ lưu trữ cho các chế độ HTTP (mặc định: localhost)
--port PORT: Cổng máy chủ cho các chế độ HTTP
--test: Chạy ở chế độ kiểm thử để xác minh chức năng

Ví dụ:

# 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

Trường url nên trỏ đến điểm cuối HTTP có thể truyền phát của máy chủ MCP của bạn (điều chỉnh máy chủ/cổng nếu cần).
Với cấu hình này, các máy khách có thể tương tác với máy chủ bằng JSON tiêu chuẩn qua các yêu cầu HTTP POST. Không yêu cầu SDK đặc biệt.
Tất cả các API công cụ chấp nhận và trả về JSON tiêu chuẩn như mô tả ở trên.

Lưu ý: Chế độ sse (Server-Sent Events) đã bị phản đối và không còn được duy trì. Vui lòng sử dụng chế độ HTTP có thể truyền phát cho tất cả các tích hợp mới.

Biến Môi trường:

Cấu hình Kết nối

Bạn có thể cấu hình kết nối StarRocks bằng cách sử dụng các biến môi trường riêng lẻ hoặc một URL kết nối duy nhất:

Tùy chọn 1: Biến Môi trường Riêng lẻ

STARROCKS_HOST: (Tùy chọn) Tên máy chủ hoặc địa chỉ IP của dịch vụ StarRocks FE. Mặc định là localhost.
STARROCKS_PORT: (Tùy chọn) Cổng giao thức MySQL của dịch vụ StarRocks FE. Mặc định là 9030.
STARROCKS_USER: (Tùy chọn) Tên người dùng StarRocks. Mặc định là root.
STARROCKS_PASSWORD: (Tùy chọn) Mật khẩu StarRocks. Mặc định là chuỗi rỗng.
STARROCKS_PASSWORD_KEYCHAIN_SERVICE: (Tùy chọn, chỉ macOS) Tên dịch vụ mật khẩu chung để sử dụng khi đọc mật khẩu từ Keychain. Chỉ được sử dụng khi không có mật khẩu rõ ràng nào được cung cấp qua STARROCKS_PASSWORD hoặc STARROCKS_URL.
STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT: (Tùy chọn, chỉ macOS) Tên tài khoản mật khẩu chung để sử dụng khi đọc mật khẩu từ Keychain. Mặc định là người dùng StarRocks đã được giải quyết.
STARROCKS_DB: (Tùy chọn) Cơ sở dữ liệu mặc định để sử dụng nếu không được chỉ định trong các tham số công cụ hoặc URI tài nguyên. Nếu được đặt, kết nối sẽ cố gắng USE cơ sở dữ liệu này. Các công cụ như table_overview và db_overview sẽ sử dụng nó nếu phần cơ sở dữ liệu bị bỏ qua trong các tham số của chúng. Mặc định là rỗng (không có cơ sở dữ liệu mặc định).

Tùy chọn 2: URL Kết nối (được ưu tiên hơn các biến riêng lẻ)

STARROCKS_URL: (Tùy chọn) Một chuỗi URL kết nối chứa tất cả các tham số kết nối trong một biến duy nhất. Định dạng: [<schema>://]user:password@host:port/database. Phần lược đồ là tùy chọn. Khi biến này được đặt, nó được ưu tiên hơn các biến riêng lẻ STARROCKS_HOST, STARROCKS_PORT, STARROCKS_USER, STARROCKS_PASSWORD và STARROCKS_DB.

Ví dụ:
- root:mypass@localhost:9030/test_db
- mysql://admin:[email protected]:9030/production
- starrocks://user:[email protected]:9030/analytics

Ưu tiên mật khẩu:

Mật khẩu được nhúng trong STARROCKS_URL được ưu tiên, bao gồm cả mật khẩu rỗng rõ ràng như user:@host:9030/db.
Nếu STARROCKS_URL bỏ qua mật khẩu, STARROCKS_PASSWORD được sử dụng khi được đặt.
Nếu không có nguồn mật khẩu rõ ràng nào được đặt và STARROCKS_PASSWORD_KEYCHAIN_SERVICE được cấu hình, mật khẩu sẽ được đọc từ macOS Keychain.

Ví dụ về macOS Keychain

Lưu mật khẩu:

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

Xác minh mật khẩu đã lưu:

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

Sử dụng nó với máy chủ này:

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

Cấu hình Bổ sung

STARROCKS_FE_ARROW_FLIGHT_SQL_PORT: (Tùy chọn) Cổng Arrow Flight SQL của dịch vụ StarRocks FE. Khi được đặt, máy chủ kết nối bằng giao thức Arrow Flight SQL hiệu suất cao (qua trình điều khiển ADBC) thay vì giao thức MySQL tiêu chuẩn. Để trống để sử dụng kết nối MySQL mặc định. Máy chủ, người dùng và mật khẩu được lấy từ các cài đặt kết nối tương tự được mô tả ở trên.
STARROCKS_OVERVIEW_LIMIT: (Tùy chọn) Giới hạn ký tự xấp xỉ cho tổng văn bản được tạo bởi các công cụ tổng quan (table_overview, db_overview) khi tìm nạp dữ liệu để điền vào bộ nhớ đệm. Điều này giúp ngăn chặn việc sử dụng bộ nhớ quá mức cho các lược đồ rất lớn hoặc nhiều bảng. Mặc định là 20000.
STARROCKS_MCP_OUTPUT_DIR: (Tùy chọn) Thư mục được sử dụng bởi read_query khi tham số output_file của nó là đường dẫn tương đối. Mặc định là ~/.mcp-server-starrocks/output/. Thư mục được tạo theo yêu cầu. Các đường dẫn tuyệt đối được truyền cho output_file (bao gồm các đường dẫn có tiền tố ~) bỏ qua cài đặt này. Lưu ý: các tệp được ghi trên máy nơi máy chủ MCP chạy. Đối với Claude Code / Claude Desktop, máy chủ chạy cục bộ, vì vậy các tệp sẽ nằm trên máy tính xách tay của bạn. Đối với các triển khai từ xa/http, tệp nằm trên máy chủ, không phải máy khách.
STARROCKS_MYSQL_AUTH_PLUGIN: (Tùy chọn) Chỉ định plugin xác thực để sử dụng khi kết nối với dịch vụ StarRocks FE. Ví dụ: đặt thành mysql_clear_password nếu triển khai StarRocks của bạn yêu cầu xác thực mật khẩu văn bản rõ ràng (chẳng hạn như khi sử dụng một số thiết lập LDAP hoặc xác thực bên ngoài). Chỉ đặt điều này nếu môi trường của bạn yêu cầu cụ thể; nếu không, auth_plugin mặc định sẽ được sử dụng.
MCP_TRANSPORT_MODE: (Tùy chọn) Chế độ giao tiếp chỉ định cách Máy chủ MCP hiển thị các dịch vụ của nó. Các tùy chọn có sẵn:
- stdio (mặc định): Giao tiếp qua đầu vào/đầu ra tiêu chuẩn, phù hợp cho việc lưu trữ Máy chủ MCP.
- streamable-http (HTTP có thể truyền phát): Khởi động như một Máy chủ HTTP có thể truyền phát, hỗ trợ các lệnh gọi API RESTful.
- sse: (Đã phản đối, không khuyến nghị) Khởi động ở chế độ truyền phát Server-Sent Events (SSE), phù hợp cho các tình huống yêu cầu phản hồi truyền phát. Lưu ý: Chế độ SSE không còn được duy trì, khuyến nghị sử dụng thống nhất chế độ HTTP có thể truyền phát.

Thành phần

Công cụ

read_query
- Mô tả: Thực thi truy vấn SELECT hoặc các lệnh khác trả về ResultSet (ví dụ: SHOW, DESCRIBE). Tùy chọn ghi toàn bộ kết quả vào một tệp cục bộ thay vì trả về nội tuyến — hữu ích cho các kết quả quá lớn để vừa trong ngữ cảnh mô hình.
- Đầu vào:
```
{
  "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"
}
```
- Đầu ra: Nếu không có output_file, nội dung văn bản chứa kết quả truy vấn ở định dạng giống CSV với hàng tiêu đề và tóm tắt số lượng hàng. Với output_file, một tóm tắt ngắn bao gồm đường dẫn tuyệt đối đã giải quyết, số byte và số lượng hàng, cùng với một bản xem trước nhỏ. Trả về thông báo lỗi khi thất bại.
write_query
- Mô tả: Thực thi lệnh DDL (CREATE, ALTER, DROP), DML (INSERT, UPDATE, DELETE) hoặc lệnh StarRocks khác không trả về ResultSet.
- Đầu vào:
```
{
  "query": "SQL command string",
  "db": "database name (optional, uses default database if not specified)"
}
```
- Đầu ra: Nội dung văn bản xác nhận thành công (ví dụ: "Query OK, X rows affected") hoặc báo cáo lỗi. Các thay đổi được cam kết tự động khi thành công.
analyze_query
- Mô tả: Phân tích truy vấn và nhận kết quả phân tích bằng cách sử dụng hồ sơ truy vấn hoặc explain analyze.
- Đầu vào:
```
{
  "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)"
}
```
- Đầu ra: Nội dung văn bản chứa kết quả phân tích truy vấn. Sử dụng ANALYZE PROFILE FROM nếu uuid được cung cấp, nếu không sử dụng EXPLAIN ANALYZE nếu sql được cung cấp.
query_and_plotly_chart
- Mô tả: Thực thi truy vấn SQL, tải kết quả vào Pandas DataFrame và tạo biểu đồ Plotly bằng biểu thức Python được cung cấp. Được thiết kế để trực quan hóa trong các giao diện người dùng hỗ trợ.
- Đầu vào:
```
{
  "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)"
}
```
- Đầu ra: Một danh sách chứa:
  1. TextContent: Biểu diễn văn bản của DataFrame và ghi chú rằng biểu đồ dành cho hiển thị giao diện người dùng.
  2. ImageContent: Biểu đồ Plotly đã tạo được mã hóa dưới dạng ảnh PNG base64 (image/png). Trả về thông báo lỗi văn bản khi thất bại hoặc nếu truy vấn không có dữ liệu.
table_overview
- Mô tả: Nhận tổng quan về một bảng cụ thể: các cột (từ DESCRIBE), tổng số hàng và các hàng mẫu (LIMIT 3). Sử dụng bộ nhớ đệm trong bộ nhớ trừ khi refresh là true.
- Đầu vào:
```
{
  "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.
}
```
- Đầu ra: Nội dung văn bản chứa tổng quan đã định dạng (cột, số hàng, dữ liệu mẫu) hoặc thông báo lỗi. Kết quả được lưu trong bộ nhớ đệm bao gồm các lỗi trước đó nếu có.
db_overview
- Mô tả: Nhận tổng quan (cột, số hàng, hàng mẫu) cho tất cả các bảng trong một cơ sở dữ liệu được chỉ định. Sử dụng bộ nhớ đệm cấp bảng cho mỗi bảng trừ khi refresh là true.
- Đầu vào:
```
{
  "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.
}
```
- Đầu ra: Nội dung văn bản chứa tổng quan được nối cho tất cả các bảng tìm thấy trong cơ sở dữ liệu, được phân tách bằng tiêu đề. Trả về thông báo lỗi nếu không thể truy cập cơ sở dữ liệu hoặc không chứa bảng nào.

Tài nguyên

Tài nguyên Trực tiếp

starrocks:///databases
- Mô tả: Liệt kê tất cả các cơ sở dữ liệu mà người dùng được cấu hình có thể truy cập.
- Truy vấn Tương đương: SHOW DATABASES
- Loại MIME: text/plain

Mẫu Tài nguyên

starrocks:///{db}/{table}/schema
- Mô tả: Lấy định nghĩa lược đồ của một bảng cụ thể.
- Truy vấn tương đương: SHOW CREATE TABLE {db}.{table}
- Loại MIME: text/plain
starrocks:///{db}/tables
- Mô tả: Liệt kê tất cả các bảng trong một cơ sở dữ liệu cụ thể.
- Truy vấn tương đương: SHOW TABLES FROM {db}
- Loại MIME: text/plain
proc:///{+path}
- Mô tả: Truy cập thông tin hệ thống nội bộ của StarRocks, tương tự như /proc của Linux. Tham số path chỉ định nút thông tin mong muốn.
- Truy vấn tương đương: SHOW PROC '/{path}'
- Loại MIME: text/plain
- Các đường dẫn phổ biến:
  - /frontends - Thông tin về các nút FE.
  - /backends - Thông tin về các nút BE (dành cho triển khai không phải cloud native).
  - /compute_nodes - Thông tin về các nút CN (dành cho triển khai cloud native).
  - /dbs - Thông tin về cơ sở dữ liệu.
  - /dbs/<DB_ID> - Thông tin về một cơ sở dữ liệu cụ thể theo ID.
  - /dbs/<DB_ID>/<TABLE_ID> - Thông tin về một bảng cụ thể theo ID.
  - /dbs/<DB_ID>/<TABLE_ID>/partitions - Thông tin phân vùng cho một bảng.
  - /transactions - Thông tin giao dịch được nhóm theo cơ sở dữ liệu.
  - /transactions/<DB_ID> - Thông tin giao dịch cho một ID cơ sở dữ liệu cụ thể.
  - /transactions/<DB_ID>/running - Các giao dịch đang chạy cho một ID cơ sở dữ liệu.
  - /transactions/<DB_ID>/finished - Các giao dịch đã hoàn thành cho một ID cơ sở dữ liệu.
  - /jobs - Thông tin về các công việc bất đồng bộ (Schema Change, Rollup, v.v.).
  - /statistic - Thống kê cho từng cơ sở dữ liệu.
  - /tasks - Thông tin về các tác vụ agent.
  - /cluster_balance - Thông tin trạng thái cân bằng tải.
  - /routine_loads - Thông tin về các công việc Routine Load.
  - /colocation_group - Thông tin về các nhóm Colocation Join.
  - /catalog - Thông tin về các catalog đã cấu hình (ví dụ: Hive, Iceberg).

Lời nhắc

Không có lời nhắc nào được định nghĩa bởi máy chủ này.

Hành vi lưu đệm

Các công cụ table_overview và db_overview sử dụng bộ nhớ đệm trong bộ nhớ để lưu trữ văn bản tổng quan đã tạo.
Khóa bộ nhớ đệm là một bộ gồm (database_name, table_name).
Khi table_overview được gọi, nó sẽ kiểm tra bộ nhớ đệm trước. Nếu kết quả tồn tại và tham số refresh là false (mặc định), kết quả đã lưu đệm sẽ được trả về ngay lập tức. Nếu không, nó sẽ lấy dữ liệu từ StarRocks, lưu vào bộ nhớ đệm, rồi trả về.
Khi db_overview được gọi, nó sẽ liệt kê tất cả các bảng trong cơ sở dữ liệu và sau đó cố gắng truy xuất tổng quan cho từng bảng bằng cách sử dụng cùng logic lưu đệm như table_overview (kiểm tra bộ nhớ đệm trước, lấy dữ liệu nếu cần và refresh là false hoặc không có trong bộ nhớ đệm). Nếu refresh là true cho db_overview, nó sẽ buộc làm mới cho tất cả các bảng trong cơ sở dữ liệu đó.
Biến môi trường STARROCKS_OVERVIEW_LIMIT cung cấp một mục tiêu mềm cho độ dài tối đa của chuỗi tổng quan được tạo cho mỗi bảng khi điền vào bộ nhớ đệm, giúp quản lý việc sử dụng bộ nhớ.
Các kết quả đã lưu đệm, bao gồm mọi thông báo lỗi gặp phải trong quá trình lấy dữ liệu ban đầu, sẽ được lưu trữ và trả về trong các lần truy cập bộ nhớ đệm tiếp theo.

Gỡ lỗi

Sau khi khởi động máy chủ mcp, bạn có thể sử dụng inspector để gỡ lỗi:

npx @modelcontextprotocol/inspector

Bản demo

MCP Demo Image