StarRocks MCP Server

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 ：

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

环境变量：

• 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 query string" }
  • **输出：**包含查询结果的文本内容，格式类似于 CSV，包含标题行和行数摘要。失败时返回错误消息。
• write_query
  • **描述：**执行不返回 ResultSet 的 DDL（ CREATE 、 ALTER 、 DROP ）、DML（ INSERT 、 UPDATE 、 DELETE ）或其他 StarRocks 命令。
  • 输入： { "query": "SQL command string" }
  • **输出：**确认成功的文本内容（例如，“查询成功，X 行受影响”）或报告错误。成功后，更改将自动提交。
• 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\")'" }
  • **输出：**包含以下内容的列表：
    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 STARROCKS_DB env var 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 。 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 - 有关 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环境变量为填充缓存时每个表生成的概览字符串的最大长度��供了一个软目标，有助于管理内存使用情况。
• 缓存结果（包括原始提取期间遇到的任何错误消息）都会被存储并在后续缓存命中时返回。

演示