StarRocks

官方

与 StarRocks 交互

GitHub

182

你可以用 StarRocks MCP 做什么？

运行只读SQL查询 — 通过 read_query 执行 SELECT、SHOW 或 DESCRIBE 语句，并可选择将大量结果保存到文件。
执行DDL/DML命令 — 使用 write_query 运行 CREATE、INSERT、UPDATE 或 DELETE 操作，并获取受影响行数的确认。
探索数据库模式 — 通过 starrocks:// 资源列出数据库、表，并获取 SHOW CREATE TABLE 定义。
获取表和数据库概览 — 使用 table_overview 或 db_overview 获取列定义、行数和示例行，并支持内存缓存。
将查询结果可视化为图表 — 向 query_and_plotly_chart 提供SQL查询和Plotly表达式，接收图表图像。
检查集群健康状态和热点 — 通过 top_hot_tables 识别频繁访问的表，或通过 top_bad_tables 识别健康状态不佳的表，并通过 proc:// 资源访问内部系统指标。

文档

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 over 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）当未通过 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:secret@db.example.com:9030/production
- starrocks://user:pass@192.168.1.100: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 端口。设置后，服务器使用高性能的 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_CHART_OUTPUT_DIR：（可选）query_and_plotly_chart 写入交互式 HTML 图表（当 format="html" 时）的目录。默认为系统临时目录。该目录按需创建。注意： 与其他输出文件一样，图表写入在 MCP 服务器运行的机器上。
STARROCKS_CHART_INCLUDE_PLOTLYJS：（可选）控制如何将 plotly.js 打包到 HTML 图表中。cdn（默认）保持文件较小，但查看时需要网络访问；inline/true 嵌入完整库以供离线使用；也接受 directory 和 false（传递给 Plotly 的 write_html）。
STARROCKS_CHART_DEFAULT_FORMAT：（可选）当省略 format 参数时，query_and_plotly_chart 的默认输出格式。可选值为 json、png、jpeg（默认）或 html。设置为 html 可始终将交互式图表文件写入 STARROCKS_CHART_OUTPUT_DIR（带有内联 PNG 预览），而无需在每次调用时传递 format。无效值会回退到 jpeg 并发出警告。
STARROCKS_MYSQL_AUTH_PLUGIN：（可选）指定连接到 StarRocks FE 服务时使用的身份验证插件。例如，如果您的 StarRocks 部署需要明文密码身份验证（例如使用某些 LDAP 或外部身份验证设置时），则设置为 mysql_clear_password。仅在您的环境特别需要时才设置此项；否则，将使用默认的 auth_plugin。

TLS / SSL 配置

这些变量控制连接的 TLS。当它们都未设置时，底层 mysql.connector 保持其默认行为（ssl-mode=PREFERRED）：如果服务器支持 TLS，则连接加密，但服务器证书不验证。为了真正的安全，请提供 CA 证书并启用验证。

STARROCKS_SSL_DISABLED：（可选）设置为 true 以强制禁用 TLS。覆盖所有其他 SSL 设置。默认为 false。
STARROCKS_SSL_CA：（可选）用于验证 StarRocks 服务器证书的 CA 证书（PEM）路径。
STARROCKS_SSL_CERT：（可选）用于双向 TLS（mTLS）的客户端证书（PEM）路径。
STARROCKS_SSL_KEY：（可选）用于双向 TLS（mTLS）的客户端私钥（PEM）路径。
STARROCKS_SSL_VERIFY_CERT：（可选）设置为 true 以根据 CA 验证服务器证书。默认为 false。
STARROCKS_SSL_VERIFY_IDENTITY：（可选）设置为 true 以同时验证服务器主机名是否与证书匹配。默认为 false。
STARROCKS_TLS_VERSIONS：（可选）允许的 TLS 版本列表，以逗号分隔，例如 TLSv1.2,TLSv1.3。

示例（根据 CA 证书验证服务器）：

"env": {
  "STARROCKS_HOST": "your-fe-host",
  "STARROCKS_PORT": "9030",
  "STARROCKS_USER": "root",
  "STARROCKS_PASSWORD": "your-password",
  "STARROCKS_SSL_CA": "/path/to/ca.pem",
  "STARROCKS_SSL_VERIFY_CERT": "true",
  "STARROCKS_SSL_VERIFY_IDENTITY": "true"
}

对于高性能的 Arrow Flight SQL 连接（通过 STARROCKS_FE_ARROW_FLIGHT_SQL_PORT 启用），TLS 单独控制：

STARROCKS_FE_ARROW_FLIGHT_SQL_USE_TLS：（可选）设置为 true 以使用 grpc+tls:// 而非明文 grpc://。启用后，STARROCKS_SSL_CA 用作 TLS 根证书，STARROCKS_SSL_VERIFY_CERT=false（默认）跳过服务器证书验证。

安全说明：避免将明文密码直接存储在 mcp.json 中。最好从密钥管理器或环境中注入 STARROCKS_PASSWORD（和证书路径），切勿将凭据提交到版本控制。

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
- 描述： 使用查询 profile 或 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。
top_hot_tables
- 描述： 通过审计日志访问次数获取热门表。它将 information_schema.tables 与 starrocks_audit_db__.starrocks_audit_tbl__ 连接，排除 root 和 SHOW 语句，将审计 SQL 文本与表名匹配，并按 visit_count 降序排列。
- 输入：
```
{
  "db": "optional database/schema filter",
  "table": "optional table name substring filter",
  "min_start_time_ms": 1704067200000,
  "max_start_time_ms": 1704153600000,
  "top_n": 20
}
```
- 输出： 文本摘要以及包含排名行的结构化内容，包含 db、table 和 visit_count。
top_bad_tables
- 描述： 根据表健康评分获取问题表，遵循 Star Management Studio 的 top-bad-tables 逻辑。它基于 information_schema.be_tablets 和 information_schema.partitions_meta 重用表健康度计算，过滤掉系统 schema，按 table_health_score 升序排列，并返回评分最低的表。
- 输入：
```
{
  "db": "optional database/schema filter",
  "table": "optional table name substring filter",
  "top_n": 20
}
```
- 输出： 文本摘要以及包含排名行的结构化内容，包含表健康字段，例如 db、table、tablet_num、replica_score、tablet_score 和 table_health_score。
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
- 描述： 获取特定表的 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 - 关于异步作业的信息（Schema Change、Rollup 等）。
  - /statistic - 每个数据库的统计信息。
  - /tasks - 关于 agent 任务的信息。
  - /cluster_balance - 负载均衡状态信息。
  - /routine_loads - 关于 Routine Load 作业的信息。
  - /colocation_group - 关于 Colocation Join 组的信息。
  - /catalog - 关于已配置 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