⚙

StarRocks数据库连接服务

StarRocks MCP服务器作为AI助手与StarRocks数据库之间的桥梁，支持直接SQL执行、数据库探索、数据可视化及详细模式/数据概览获取，无需复杂客户端设置。

作者 By StarRocks

混合部署数据库连接 SQL执行

GitHub

StarRocks官方MCP服务器

StarRocks MCP服务器充当AI助手和StarRocks数据库之间的桥梁。它允许直接SQL执行、数据库探索、通过图表进行数据可视化，以及检索详细的模式/数据概述，而不需要复杂的客户端设置。

特性

直接SQL执行： 跑 SELECT 查询(read_query)以及DDL/DML命令(write_query).
数据库探索： 列出数据库和表，检索表模式(starrocks:// 资源）。
系统信息： 通过访问内部StarRocks指标和状态 proc:// 资源路径。
详细概述： 获取表格的全面摘要(table_overview)或整个数据库(db_overview)，包括列定义、行计数和示例数据。
数据可视化： 执行查询并直接从结果生成Plotly图表(query_and_plotly_chart).
智能缓存： 表和数据库概述缓存在内存中，以加快重复请求的速度。需要时可以绕过缓存。
灵活配置： 通过环境变量设置连接细节和行为。

配置

MCP服务器通常通过MCP主机运行。配置传递给主机，指定如何启动StarRocks MCP服务器进程。

使用流式HTTP（推荐）：

要在Streamable HTTP模式下启动服务器：

第一次测试连接正常：

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

启动服务器：

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

然后按如下方式配置MCP：

JSON``` 1 2 3 4 5 6 7{ “mcpServers”: { “mcp-server-starrocks”: { “url”: “http://localhost:8000/mcp” } } }


**使用 `uv` 已安装软件包（单个环境变量）：**


JSON```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
  "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）：

JSON``` 1 2 3 4 5 6 7 8 9 10 11{ “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` 本地目录（用于开发）：**


JSON```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20{
  "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：

JSON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16{ “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” } } } }


**命令行参数：**


服务器支持以下命令行参数：


BASH```
1uv run mcp-server-starrocks --help

--mode {stdio,sse,http,streamable-http}：传输模式（默认值：stdio或MCP_Transport_mode环境变量）
--host HOST：HTTP模式的服务器主机（默认：localhost）
--port PORT：HTTP模式的服务器端口
--test：在测试模式下运行以验证功能

示例：

BASH``` 1 2 3 4 5 6# 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_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_OVERVIEW_LIMIT`：（可选） *近似* 字符限制 *总计* 由概述工具生成的文本(`table_overview`, `db_overview`)在获取数据以填充缓存时。这有助于防止非常大的模式或大量表的过度内存使用。默认为 `20000`.
- `STARROCKS_MYSQL_AUTH_PLUGIN`：（可选）指定连接到StarRocks FE服务时使用的身份验证插件。例如，设置为 `mysql_clear_password` 如果您的StarRocks部署需要明文密码身份验证（例如在使用某些LDAP或外部身份验证设置时）。仅当您的环境特别需要时才设置此项；否则，将使用默认的auth_plugin。
- `MCP_TRANSPORT_MODE`：（可选）指定MCP服务器如何公开其服务的通信模式。可用选项：


- `stdio` （默认）：通过标准输入/输出进行通信，适用于MCP主机托管。
- `streamable-http` （流式HTTP）：作为流式HTTP服务器启动，支持RESTful API调用。
- `sse`: **（已弃用，不推荐）** 以服务器发送事件（SSE）流模式启动，适用于需要流式响应的场景。 **注意：SSE模式不再维护，建议统一使用Streamable HTTP模式。**


## 组件


### 工具


- `read_query`


- **说明：** 执行SELECT查询或返回ResultSet的其他命令（例如。， `SHOW`, `DESCRIBE`).
- **输入：**

JSON```
1
2
3
4{
  "query": "SQL query string",
  "db": "database name (optional, uses default database if not specified)"
}

输出： 包含CSV格式查询结果的文本内容，包括标题行和行计数摘要。失败时返回错误消息。
write_query
说明： 执行DDL(CREATE, ALTER, DROP)，DML(INSERT, UPDATE, DELETE)，或其他不返回ResultSet的StarRocks命令。
输入：

JSON``` 1 2 3 4{ “query”: “SQL command string”, “db”: “database name (optional, uses default database if not specified)” }

- **输出：** 确认成功的文本内容（例如，“查询正常，X行受影响”）或报告错误。成功后会自动提交更改。
- `analyze_query`


- **说明：** 使用查询配置文件或解释分析来分析查询并获得分析结果。
- **输入：**

JSON```
1
2
3
4
5{
  "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)"
}

输出： 包含查询分析结果的文本内容。用途 ANALYZE PROFILE FROM 如果提供了uuid，否则使用 EXPLAIN ANALYZE 如果提供了sql。
query_and_plotly_chart
说明： 执行SQL查询，将结果加载到Pandas DataFrame中，并使用提供的Python表达式生成Plotly图表。设计用于支持UI的可视化。
输入：

JSON``` 1 2 3 4 5{ “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` 这是真的。
- **输入：**

JSON```
1
2
3
4{
  "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 这是真的。
输入：

JSON``` 1 2 3 4{ “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`The `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服务器后，您可以使用inspector进行调试：

1npx @modelcontextprotocol/inspector


## 演示