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

前提条件

Python 3.11 或更高版本。
一个可访问的 StarRocks 集群（FE 服务）。默认情况下，服务器通过 MySQL 协议连接到 localhost:9030。
uv — 来自 Astral 的快速 Python 包和项目管理器（是 pip + virtualenv 的现代替代品）。本项目使用 uv 来解析依赖、创建虚拟环境并启动服务器。本 README 中的 uv run 命令会在首次使用时自动创建隔离环境并安装所需依赖，因此无需手动执行 pip install 步骤。

安装 `uv`

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via Homebrew / pipx / pip
brew install uv
# pipx install uv
# pip install uv

有关其他选项，请参阅官方 uv 安装指南。安装后，验证它是否在您的 PATH 中：

uv --version

安装

您通常不需要手动安装该包 — MCP 主机会通过 uv 为您启动它（请参阅下面的配置）。uv 会按需获取该包及其依赖项。

要直接运行以进行测试或开发：

# Run the published package in a throwaway environment
uv run --with mcp-server-starrocks mcp-server-starrocks --help

# Or, from a local checkout of this repository
git clone https://github.com/starrocks/mcp-server-starrocks.git
cd mcp-server-starrocks
uv sync                      # create the virtual environment and install dependencies
uv run mcp-server-starrocks --help

配置

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

使用 Streamable HTTP（推荐）：

要以 Streamable HTTP 模式启动服务器：

首先测试与 StarRocks 的连接是否正常（9030 是 StarRocks MySQL 协议端口，而非 HTTP 服务器端口）：

$ STARROCKS_URL=root:@localhost:9030 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", // <-- Update this path
        "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"
      }
    }
  }
}

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

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mcp-server-starrocks", // <-- Update this path
        "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：以测试模式运行以验证功能

示例：

# Start in streamable HTTP mode on custom host/port
uv run mcp-server-starrocks --mode streamable-http --host 0.0.0.0 --port 8080

# Start in stdio mode (default)
uv run mcp-server-starrocks --mode stdio

# Run test mode
uv run mcp-server-starrocks --test

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

注意： 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）当从钥匙串读取密码时使用的通用密码服务名称。仅在未通过 STARROCKS_PASSWORD 或 STARROCKS_URL 提供显式密码时使用。
STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT：（可选，仅限 macOS）当从钥匙串读取密码时使用的通用密码账户名称。默认为解析后的 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:[email protected]:9030/production
- starrocks://user:[email protected]:9030/analytics

密码优先级：

嵌入在 STARROCKS_URL 中的密码优先，包括像 user:@host:9030/db 这样的显式空密码。
如果 STARROCKS_URL 省略了密码，则使用 STARROCKS_PASSWORD（如果已设置）。
如果两个显式密码源都未设置且配置了 STARROCKS_PASSWORD_KEYCHAIN_SERVICE，则从 macOS 钥匙串读取密码。

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_FE_ARROW_FLIGHT_SQL_PORT：（可选）StarRocks FE 服务的 Arrow Flight SQL 端口。设置后，服务器使用高性能的 Arrow Flight SQL 协议（通过 ADBC 驱动程序）连接，而非标准的 MySQL 协议。不设置则使用默认的 MySQL 连接。主机、用户和密码取自上述相同的连接设置。
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 服务时使用的身份验证插件。例如，如果您的 StarRocks 部署需要明文密码身份验证（例如使用某些 LDAP 或外部身份验证设置时），则设置为 mysql_clear_password。仅在您的环境特别需要时才设置此项；否则，将使用默认的 auth_plugin。
MCP_TRANSPORT_MODE：（可选）通信模式，指定 MCP 服务器如何公开其服务。可用选项：
- stdio（默认）：通过标准输入/输出进行通信，适用于 MCP 主机托管。
- streamable-http（Streamable HTTP）：作为 Streamable HTTP 服务器启动，支持 RESTful API 调用。
- sse：（已弃用，不推荐） 以服务器发送事件（SSE）流模式启动，适用于需要流式响应的场景。注意：SSE 模式不再维护，建议统一使用 Streamable HTTP 模式。

组件

工具

read_query

描述： 执行 SELECT 查询或其他返回结果集的命令（例如 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）或其他不返回结果集的 StarRocks 命令。
- 输入：
```
{
  "query": "SQL command string",
  "db": "database name (optional, uses default database if not specified)"
}
```
- 输出： 确认成功的文本内容（例如，“Query OK, X rows affected”）或报告错误。成功时更改会自动提交。
analyze_query
- 描述： 分析查询并使用查询配置文件或 explain analyze 获取分析结果。
- 输入：
```
{
  "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)"
}
```
- 输出： 包含查询分析结果的文本内容。如果提供了 uuid，则使用 ANALYZE PROFILE FROM；如果提供了 sql，则使用 EXPLAIN ANALYZE。
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 显示的说明。
  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 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。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 或缓存未命中，则进行获取）来检索 每个表 的概览。如果 refresh 对于 db_overview 为 true，则会强制刷新该数据库中的所有表。
STARROCKS_OVERVIEW_LIMIT 环境变量为填充缓存时 每个表 生成的概览字符串的最大长度提供了一个 软目标，有助于管理内存使用。
缓存的结果，包括在原始获取过程中遇到的任何错误消息，都会被存储并在后续缓存命中时返回。

调试

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

npx @modelcontextprotocol/inspector

演示

MCP Demo Image

文档