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)。
• 智能缓存： 表和数据库概览在内存中缓存以加快重复请求的速度。必要时可以绕过缓存。
• 灵活配置： 通过环境变量设置连接详情和行为。

配置

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

使用已安装包的 uv：

json
{
"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",
"STARROCKS_OVERVIEW_LIMIT": "default 20000",
"STARROCKS_MYSQL_AUTH_PLUGIN":"mysql_clear_password"
}
}
}
}

使用本地目录的 uv（用于开发）：

json
{
"mcpServers": {
"mcp-server-starrocks": {
"command": "uv",
"args": [
"--directory",
"path/to/mcp-server-starrocks", // <-- 更新此路径
"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",
"STARROCKS_OVERVIEW_LIMIT": "default 20000",
"STARROCKS_MYSQL_AUTH_PLUGIN":"mysql_clear_password"
}
}
}
}

使用可流式 HTTP（推荐用于集成）：

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

要以可流式 HTTP 模式启动服务器：

bash
export MCP_TRANSPORT_MODE=streamable-http
uv run mcp-server-starrocks

• url 字段应指向您的 MCP 服务器的可流式 HTTP 端点（根据需要调整主机/端口）。
• 使用此配置，客户端可以通过标准 JSON 格式的 HTTP POST 请求与服务器交互。不需要特殊的 SDK。
• 所有工具 API 接受并返回如上所述的标准 JSON。

注意：
sse（服务器发送事件）模式已被弃用且不再维护。请为所有新集成使用可流式 HTTP 模式。

环境变量：

• 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 这样的工具在它们的参数中省略数据库部分时会使用这个设置。默认为空（无默认数据库）。
• STARROCKS_OVERVIEW_LIMIT: （可选）概述工具（如 table_overview、db_overview）在获取数据填充缓存时生成的 总 文本的 近似 字符限制。这有助于防止非常大的模式或大量表导致内存使用过多。默认为 20000。
• STARROCKS_MYSQL_AUTH_PLUGIN: （可选）指定连接到 StarRocks FE 服务时使用的认证插件。例如，如果你的 StarRocks 部署需要明文密码认证（比如使用某些 LDAP 或外部认证设置），则可以设置为 mysql_clear_password。仅当你的环境特别需要时才设置此选项；否则，将使用默认的 auth_plugin。
• MCP_TRANSPORT_MODE: （可选）通信模式，指定 MCP 服务器如何暴露其服务。可用选项：
  • stdio（默认）：通过标准输入/输出进行通信，适用于 MCP 主机托管。
  • streamable-http（流式 HTTP）：以流式 HTTP 服务器启动，支持 RESTful API 调用。
  • sse：（已弃用，不推荐） 以 Server-Sent Events (SSE) 流模式启动，适用于需要流响应的场景。注意：SSE 模式不再维护，建议统一使用流式 HTTP 模式。

组件

工具

• read_query

  • 描述： 执行一个 SELECT 查询或其他返回 ResultSet 的命令（例如 SHOW、DESCRIBE）。
  • 输入： { "query": "SQL 查询字符串" }
  • 输出： 包含查询结果的类似 CSV 格式的文本内容，包括标题行和行数摘要。失败时返回错误消息。

• write_query

  • 描述： 执行 DDL（CREATE、ALTER、DROP）、DML（INSERT、UPDATE、DELETE）或其他不返回 ResultSet 的 StarRocks 命令。
  • 输入： { "query": "SQL 命令字符串" }
  • 输出： 确认成功的文本内容（例如，“Query OK, X rows affected”）或报告错误。成功时自动提交更改。

• query_and_plotly_chart

  • 描述： 执行 SQL 查询，将结果加载到 Pandas DataFrame 中，并使用提供的 Python 表达式生成 Plotly 图表。设计用于支持 UI 的可视化。

  • 输入：
    json
    {
    "query": "获取数据的 SQL 查询",
    "plotly_expr": "使用 'px'（Plotly Express）和 'df'（DataFrame）的 Python 表达式字符串。示例：'px.scatter(df, x="col1", y="col2")'"
    }

  • 输出： 包含以下内容的列表：

    1. TextContent：DataFrame 的文本表示以及图表用于 UI 显示的说明。
    2. ImageContent：生成的 Plotly 图表编码为 base64 PNG 图像 (image/png)。失败或查询没有数据时返回文本错误消息。

• table_overview

  • 描述： 获取特定表的概览：列（来自 DESCRIBE）、总行数和样本行（LIMIT 3）。除非 refresh 为 true，否则使用内存缓存。
  • 输入：
    json
    {
    "table": "表名，可选地带有数据库名前缀（例如，'db_name.table_name' 或 'table_name'）。如果省略了数据库，则使用 STARROCKS_DB 环境变量（如果已设置）。",
    "refresh": false // 可选，布尔值。设为 true 以绕过缓存。默认为 false。
    }- 输出: 包含格式化概览（列、行数、示例行）的文本内容，或错误消息。缓存结果包括之前的错误（如果适用）。

• db_overview

  • 描述: 获取指定数据库中_所有_表的概览（列、行数、示例行）。除非 refresh 为 true，否则使用每个表的表级缓存。

  • 输入:
    json
    {
    "db": "database_name", // 如果设置了 STARROCKS_DB 环境变量，则可选。
    "refresh": false // 可选，布尔值。设置为 true 以绕过该数据库中所有表的缓存。默认为 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 - 异步任务（如 Schema Change, 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 或缓存未命中）来检索每个表的概览。如果 db_overview 的 refresh 为 true，则强制刷新该数据库中的_所有_表。- STARROCKS_OVERVIEW_LIMIT 环境变量为每个表在填充缓存时生成的概览字符串的最大长度提供了一个_软目标_，有助于管理内存使用。
• 缓存的结果，包括在原始获取过程中遇到的任何错误消息，都会被存储并在后续的缓存命中时返回。

演示