StarRocks MCP Server

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模式下启动服务器：

第一次测试连接正常：

$ STARROCKS_URL=root:@localhost:8000 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", //  **注：**
> 这 `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字符串。格式： `[://]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` wins，包括一个明确的空密码，如 `user:@host:9030/db`.
- 如果 `STARROCKS_URL` 省略密码， `STARROCKS_PASSWORD` 设置时使用。
- 如果未设置显式密码源 `STARROCKS_PASSWORD_KEYCHAIN_SERVICE` 如果已配置，则从macOS Keychain读取密码。

**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_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服务时使用的身份验证插件。例如，设置为 `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`).可以选择将完整结果写入本地文件，而不是内联返回——这对于太大而无法放入模型上下文的结果很有用。
  - **输入：**

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

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

- `analyze_query`

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

{ "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的可视化。
  - **输入：**

{ "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显示的注释。
    1. `ImageContent`：生成的Plotly图表编码为base64 PNG图像(`image/png`).如果查询失败或未生成数据，则返回文本错误消息。

- `table_overview`

  - **说明：** 获取特定表的概述：列（来自 `DESCRIBE`)、总行数和样本行(`LIMIT 3`).使用内存缓存，除非 `refresh` 这是真的。
  - **输入：**

{ "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` 这是真的。
  - **输入：**

{ "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/` -按ID显示特定数据库的信息。
    - `/dbs//` -按ID显示特定表的信息。
    - `/dbs///partitions` -表的分区信息。
    - `/transactions` -按数据库分组的交易信息。
    - `/transactions/` -特定数据库ID的事务信息。
    - `/transactions//running` -正在为数据库ID运行事务。
    - `/transactions//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进行调试：

npx @modelcontextprotocol/inspector

## 演示