StarRocks MCP Server

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 是 StarRocks MySQL 協定埠，而非 HTTP 伺服器埠）：

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

使用 uv 搭配本機目錄和連線 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"
      }
    }
  }
}

命令列引數：

伺服器支援以下命令列引數：

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 端點（根據需要調整主機/埠）。
透過此配置，用戶端可以使用標準 JSON 透過 HTTP POST 請求與伺服器互動。無需特殊的 SDK。
所有工具 API 都接受並回傳如上所述的標準 JSON。

注意： sse（伺服器傳送事件）模式已棄用且不再維護。請對所有新的整合使用 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）從 Keychain 讀取密碼時使用的通用密碼服務名稱。僅在未透過 STARROCKS_PASSWORD 或 STARROCKS_URL 提供明確密碼時使用。
STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT：（選用，僅限 macOS）從 Keychain 讀取密碼時使用的通用密碼帳戶名稱。預設為解析後的 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 Keychain 讀取密碼。

macOS Keychain 範例

儲存密碼：

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 埠。設定後，伺服器將使用高效能的 Arrow Flight SQL 協定（透過 ADBC 驅動程式）連線，而非標準的 MySQL 協定。保留未設定則使用預設的 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：（已棄用，不建議使用） 以伺服器傳送事件（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：產生的 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 為 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}
- 描述： 存取 StarRocks 內部系統資訊，類似 Linux 的 /proc。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 - 關於非同步作業的資訊（例如結構變更、Rollup 等）。
  - /statistic - 每個資料庫的統計資訊。
  - /tasks - 關於代理任務的資訊。
  - /cluster_balance - 負載平衡狀態資訊。
  - /routine_loads - 關於 Routine Load 作業的資訊。
  - /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 或快取未命中時才擷取）來擷取 每個資料表 的概覽。如果 refresh 對於 db_overview 為 true，則會強制重新整理該資料庫中的所有資料表。
STARROCKS_OVERVIEW_LIMIT 環境變數提供一個 軟性目標，用於在填入快取時，限制 每個資料表 產生的概覽字串的最大長度，以協助管理記憶體使用量。
快取的結果，包括原始擷取期間遇到的任何錯誤訊息，都會被儲存起來，並在後續快取命中時回傳。

除錯

啟動 mcp 伺服器後，您可以使用 inspector 進行除錯：

npx @modelcontextprotocol/inspector

示範

MCP Demo Image

文件