mcp-server-starrocks

StarRocks 官方 MCP 服务器

功能

• 直接 SQL 执行: 运行 SELECT 查询 (read_query) 和 DDL/DML 命令 (write_query)。

• 数据库探索: 列出数据库和表，检索表模式 (starrocks:// 资源)。

• 系统信息: 通过 proc:// 资源路径访问 StarRocks 内部指标和状态。

• 详细概览: 获取表 (table_overview) 或整个数据库 (db_overview) 的综合摘要，包括列定义、行数和示例数据。

• 数据可视化: 执行查询并直接从结果生成 Plotly 图表 (query_and_plotly_chart)。

• 智能缓存: 表和数据库概览缓存在内存中，以加速重复请求。需要时可以绕过缓存。

• 灵活配置: 通过环境变量设置连接细节和行为。

配置

• 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。

组件

工具

• 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 中进行可视化。
• 输入:
• 输出: 包含以下内容的列表：
1. TextContent: DataFrame 的文本表示和说明图表用于 UI 显示的注释。
2. ImageContent: 生成的 Plotly 图表编码为 base64 PNG 图像 (image/png)。失败或查询无数据时返回文本错误消息。

• table_overview
• 描述: 获取特定表的概览：列（来自 DESCRIBE）、总行数和示例行 (LIMIT 3)。除非 refresh 为 true，否则使用内存缓存。
• 输入:
• 输出: 包含格式化概览（列、行数、示例数据）或错误消息的文本内容。缓存结果包括先前的错误（如果适用）。

• db_overview
• 描述: 获取指定数据库中 所有 表的概览（列、行数、示例行）。除非 refresh 为 true，否则对每个表使用表级缓存。
• 输入:
• 输出: 包含数据库中所有表的连接概览的文本内容，用标题分隔。如果无法访问数据库或数据库中没有表，则返回错误消息。

资源

直接资源

• 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 环境变量提供了在填充缓存时 每个表 生成的概览字符串的 软目标 最大长度，有助于管理内存使用。

• 缓存结果，包括原始获取期间遇到的任何错误消息，都会被存储并在后续缓存命中时返回。

演示