【技术文档摘要】：

StarRocks 官方 MCP 服务器

StarRocks MCP 服务器作为AI助手与StarRocks数据库之间的桥梁。它允许直接执行SQL查询，探索数据库，通过图表进行数据可视化，并获取详细的模式/数据概览，而无需复杂的客户端设置。

<a href="https://glama.ai/mcp/servers/@StarRocks/mcp-server-starrocks"> <img width="380" height="200" src="https://gips1.baidu.com/it/u=3684147848,2558622463&fm=3081&app=3081&f=PNG?w=760&h=400" alt="StarRocks Server MCP 服务器" /> </a>

功能

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

配置

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

使用流式HTTP（推荐）：

要以流式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": "默认 localhost",
        "STARROCKS_PORT": "默认 9030",
        "STARROCKS_USER": "默认 root",
        "STARROCKS_PASSWORD": "默认 空",
        "STARROCKS_DB": "默认 空"
      }
    }
  }
}

使用已安装包的 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", // <-- 更新此路径
        "run",
        "mcp-server-starrocks"
      ],
      "env": {
        "STARROCKS_HOST": "默认 localhost",
        "STARROCKS_PORT": "默认 9030",
        "STARROCKS_USER": "默认 root",
        "STARROCKS_PASSWORD": "默认 空",
        "STARROCKS_DB": "默认 空"
      }
    }
  }
}

使用 uv 的本地目录和连接URL：

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mcp-server-starrocks", // <-- 更新此路径
        "run",
        "mcp-server-starrocks"
      ],
      "env": {
        "STARROCKS_URL": "root:password@localhost:9030/my_database"
      }
    }
  }
}

命令行参数：

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

uv run mcp-server-starrocks --help

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

示例：

# 在自定义主机/端口上以流式HTTP模式启动
uv run mcp-server-starrocks --mode streamable-http --host 0.0.0.0 --port 8080

# 以stdio模式启动（默认）
uv run mcp-server-starrocks --mode stdio

# 运行测试模式
uv run mcp-server-starrocks --test

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

注意： sse（服务器发送事件）模式已弃用且不再维护。请为所有新集成使用流式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服务时使用的身份验证插件。例如，如果您的StarRocks部署需要明文密码身份验证（如使用某些LDAP或外部身份验证设置时），则设置为 mysql_clear_password。仅在您的环境中特别需要时才设置；否则，使用默认的身份验证插件。

• MCP_TRANSPORT_MODE: （可选）通信模式，指定MCP服务器如何公开其服务。可用选项：

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

组件

工具

• read_query

  • 描述： 执行一个SELECT查询或其他返回ResultSet的命令（例如，SHOW、DESCRIBE）。
  • 输入：

    {
      "query": "SQL查询字符串",
      "db": "数据库名称（可选，未指定时使用默认数据库）"
    }
    

  • 输出： 包含查询结果的文本内容，类似于CSV格式，包括标题行和行数总结。失败时返回错误消息。

• write_query

  • 描述： 执行DDL（CREATE、ALTER、DROP）、DML（INSERT、UPDATE、DELETE）或其他不返回ResultSet的StarRocks命令。
  • 输入：

    {
      "query": "SQL命令字符串",
      "db": "数据库名称（可选，未指定时使用默认数据库）"
    }
    

  • 输出： 确认成功的文本内容（例如，“Query OK, X rows affected”）或报告错误。成功时自动提交更改。

• analyze_query

  • 描述： 分析查询并使用查询分析或解释分析获取分析结果。
  • 输入：

    {
      "uuid": "查询ID，由32个十六进制数字组成的字符串，格式为8-4-4-4-12",
      "sql": "要分析的查询SQL",
      "db": "数据库名称（可选，未指定时使用默认数据库）"
    }
    

  • 输出： 包含查询分析结果的文本内容。如果提供了uuid，则使用 ANALYZE PROFILE FROM，否则如果提供了sql，则使用 EXPLAIN ANALYZE。

• query_and_plotly_chart

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

    {
      "query": "用于获取数据的SQL查询",
      "plotly_expr": "使用'px'（Plotly Express）和'df'（DataFrame）的Python表达式字符串。示例：'px.scatter(df, x=\"col1\", y=\"col2\")'",
      "db": "数据库名称（可选，未指定时使用默认数据库）"
    }
    

  • 输出： 包含以下内容的列表：
    1. TextContent：DataFrame的文本表示和图表用于UI显示的说明。
    2. ImageContent：生成的Plotly图表编码为base64 PNG图像（image/png）。失败或查询没有数据时返回文本错误消息。

• table_overview

  • 描述： 获取特定表的概述：列（来自 DESCRIBE）、总行数和样本行（LIMIT 3）。除非 refresh 为真，否则使用内存中的缓存。
  • 输入：

    {
      "table": "表名，可选地以前缀数据库名（例如，'db_name.table_name' 或 'table_name'）。如果省略数据库，则使用设置的 STARROCKS_DB 环境变量。",
      "refresh": false // 可选，布尔值。设置为 true 以绕过缓存。默认为 false。
    }
    

  • 输出： 包含格式化概述（列、行数、样本数据）的文本内容或错误消息。缓存结果包括适用的先前错误。

• db_overview

  • 描述： 获取指定数据库内所有表的概述（列、行数、样本行）。除非 refresh 为真，否则对每个表使用表级缓存。
  • 输入：

    {
      "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 - 异步作业（模式变更、汇总等）的信息。
    • /statistic - 每个数据库的统计信息。
    • /tasks - 关于代理任务的信息。
    • /cluster_balance - 负载均衡状态信息。
    • /routine_loads - 关于例行加载作业的信息。
    • /colocation_group - 关于共位置联接组的信息。
    • /catalog - 关于配置的目录（例如Hive、Iceberg）的信息。

提示

此服务器未定义提示。

缓存行为

• table_overview 和 db_overview 工具利用内存中的缓存存储生成的概述文本。
• 缓存键是一个元组 (数据库名称, 表名称)。
• 当调用 table_overview 时，它首先检查缓存。如果存在结果且 refresh 参数为 false（默认），则立即返回缓存的结果。否则，它从StarRocks获取数据，将其存储在缓存中，然后返回。
• 当调用 db_overview 时，它列出数据库中的所有表，然后尝试使用相同的缓存逻辑（先检查缓存，需要时获取且 refresh 为 false 或缓存未命中）为每个表检索概述。如果 db_overview 的 refresh 为 true，则强制刷新该数据库内的所有表。
• STARROCKS_OVERVIEW_LIMIT 环境变量提供了一个每张表填充缓存时生成的概述字符串的最大长度的软目标，帮助管理内存使用。
• 缓存结果，包括最初获取时遇到的任何错误消息，被存储并在后续缓存命中时返回。

调试

启动mcp服务器后，可以使用检查器进行调试：

npx @modelcontextprotocol/inspector

演示