1. 为什么要在 StarRocks 前面加一层 MCP Server如果你正在做 LLM 驱动的数据分析应用大概率遇到过这个尴尬模型能写 SQL但拿不到真实表结构能生成查询却没法直接执行好不容易跑通了换一个模型客户端又得重写一遍工具调用逻辑。StarRocks MCP Server 开源之后这件事有了一个相对标准的解法——它把 StarRocks 的库表探查、只读查询、写入执行、甚至 Plotly 图表生成统一封装成 MCP 协议下的工具和资源任何支持 MCP 的客户端Claude Desktop、Cline、DeepChat 等都能直接调用。一句话概括StarRocks MCP Server 是一个让 LLM 用标准协议访问 StarRocks 的适配层适合做数据问答、智能报表、自动分析 Agent 的开发者。它解决的不是“StarRocks 查询快不快”而是“模型怎么知道该查哪张表、怎么把结果拿回来、怎么把图表还给用户”。本文按落地顺序走一遍先准备 StarRocks 和数据再配置 MCP 客户端然后验证连通性最后把常见报错逐个拆掉。2. 前置准备StarRocks 集群与 MCP 运行环境2.1 StarRocks 侧要满足的条件MCP Server 本质是一个客户端进程它通过 MySQL 协议连到 StarRocks 的 FE 查询端口默认 9030。所以你需要一个可访问的 StarRocks 集群FE 的 9030 端口对 MCP Server 所在机器开放一个具备目标库读权限的账号如果要用 write_query 工具还需要对应的 DDL/DML 权限目标库里有真实数据否则 table_overview 返回的样本行是空的模型会“无米下炊”。本地快速验证可以用 Docker 起一个 all-in-one 实例FE/BE 都在一个容器里适合跑通链路docker run -d --name starrocks \ -p 9030:9030 -p 8030:8030 -p 8040:8040 \ starrocks/allin1-ubuntu:latest等容器日志出现 FE 启动完成后用 MySQL 客户端连一下确认mysql -h 127.0.0.1 -P 9030 -u root -e SHOW DATABASES;2.2 准备一张可分析的表为了让后面的对话式分析有东西可查建一张带时间维度和分组字段的表并塞几条数据CREATE DATABASE IF NOT EXISTS demo; USE demo; CREATE TABLE IF NOT EXISTS sales ( dt DATE, region VARCHAR(32), channel VARCHAR(32), amount DECIMAL(18,2) ) ENGINEOLAP DUPLICATE KEY(dt, region) DISTRIBUTED BY HASH(region) BUCKETS 4 PROPERTIES (replication_num 1); INSERT INTO sales VALUES (2024-05-01,east,app,1200.50), (2024-05-01,east,web,800.00), (2024-05-02,west,app,1500.00), (2024-05-02,west,web,600.25), (2024-05-03,east,app,980.00);这张表结构简单、字段语义清晰模型通过 table_overview 拿到列定义和样本后很容易自己写出SELECT region, SUM(amount) ... GROUP BY region这类聚合。2.3 MCP Server 的获取方式StarRocks MCP Server 是开源项目仓库在 GitHub 的 StarRocks/mcp-server-starrocks。它提供 Python 包和可执行入口常见做法是用 uv 或 pip 安装后在 MCP 客户端配置里以 stdio 方式拉起。核心配置项就三个StarRocks 主机、查询端口、账号密码外加一个可选的默认数据库。3. 可复制的 MCP 配置骨架3.1 客户端配置结构MCP 客户端的配置基本都是 JSON结构是mcpServers下挂一个服务名里面声明启动命令和参数。下面这份骨架可以直接改{ mcpServers: { starrocks: { command: uvx, args: [ mcp-server-starrocks ], env: { STARROCKS_HOST: 127.0.0.1, STARROCKS_PORT: 9030, STARROCKS_USER: root, STARROCKS_PASSWORD: , STARROCKS_DB: demo } } } }几个参数的含义对照如下参数作用常见取值STARROCKS_HOSTFE 地址127.0.0.1 或内网 IPSTARROCKS_PORTFE 查询端口9030STARROCKS_USER连接账号root 或只读账号STARROCKS_PASSWORD账号密码空密码留空字符串STARROCKS_DB默认库demo可省略注意如果你的客户端不支持 uvx可以先用pip install mcp-server-starrocks装到本地虚拟环境再把 command 换成该环境下的可执行文件绝对路径避免“命令找不到”的问题。3.2 不同客户端的差异点Claude Desktop 的配置文件在claude_desktop_config.jsonCline 在 VS Code 插件设置里粘贴同一段 JSONDeepChat 则在对话设置里添加 MCP Server。结构一致区别只在“配置放哪”。有一点要提前想清楚query_and_plotly_chart 返回的是 Base64 图片部分客户端不渲染图片只显示一坨文本。如果你主要做可视化选客户端时把图片渲染能力纳入考量。3.3 权限最小化建议生产环境不要用 root 跑 MCP。建一个只读账号只授予目标库的 SELECTCREATE USER mcp_ro% IDENTIFIED BY your_password; GRANT SELECT ON demo.* TO mcp_ro%;这样即使模型误触发 write_query也会被权限挡住比事后审计更省心。4. 验证连通性从工具列表到一次真实查询4.1 确认工具已注册配置保存后重启客户端在对话界面查看可用工具列表。正常情况下能看到 db_overview、table_overview、read_query、write_query、query_and_plotly_chart 这几个。如果列表为空说明 MCP Server 没起来先去看客户端日志里的 stderr。4.2 用自然语言触发一次探查直接对模型说“列出 demo 库里的表并告诉我 sales 表有哪些字段。”模型会先调 db_overview再调 table_overview返回列定义、总行数和前 3 行样本。这一步能跑通说明“模型 → MCP Client → MCP Server → StarRocks”整条链路是活的。4.3 验证只读查询接着问“按 region 汇总 sales 的 amount从高到低排。”模型会生成类似下面的 SQL 并通过 read_query 执行SELECT region, SUM(amount) AS total FROM demo.sales GROUP BY region ORDER BY total DESC;返回结果以 CSV 形式回到模型上下文模型再转成表格给你。实测下来只要表结构清晰模型生成的聚合 SQL 基本不需要人工纠正。4.4 验证图表工具如果客户端支持图片可以问“把上面结果画成柱状图。”模型会调用 query_and_plotly_chart传入 SQL 和一段 Plotly Express 表达式比如px.bar(df, xregion, ytotal)最终返回 Base64 图片。这一步是 StarRocks MCP Server 比较有辨识度的能力——它把“取数”和“出图”合并成一个工具调用省掉了中间手工拼图的环节。5. 本篇常见报错排查5.1 连接被拒绝Connection refused现象是 MCP Server 启动后立刻退出日志里出现连接 9030 失败。先确认 FE 端口是否真的在监听telnet 127.0.0.1 9030。如果是 Docker 部署注意容器端口映射有没有漏掉 9030。还有一种情况是 MCP Server 跑在另一台机器而 StarRocks 只绑了 127.0.0.1需要把 FE 的 priority_networks 配成内网网段。5.2 认证失败Access denied多半是账号密码或授权主机不匹配。StarRocks 的用户是userhost形式mcp_ro%和mcp_rolocalhost是两个不同账号。用SHOW GRANTS FOR mcp_ro%;确认权限再检查配置里的密码有没有多余空格。5.3 工具列表为空配置写对了但客户端看不到工具通常是 command 路径问题。uvx 不在客户端的 PATH 里时进程根本起不来。解决办法是写绝对路径或者先在终端手动执行一遍uvx mcp-server-starrocks看能否正常启动并等待 stdio 输入。5.4 查询超时或结果过大read_query 默认会把整个结果集拉回来如果模型写了个没有 LIMIT 的全表扫描大表上很容易超时。两个办法一是给 MCP 账号加资源组限制二是养成在提示词里要求“先 LIMIT 100 看样本”的习惯。table_overview 本身只取 3 行样本相对安全。5.5 图表不显示前面提过部分客户端不渲染 Base64 图片。先确认工具确实被调用了看调用日志再确认客户端版本是否支持图片消息。如果只是想要数据用 read_query 就够了不必强求图表。6. 把 SQL 分析能力接进你的 AI 应用链路跑通之后接下来就是把它变成产品能力。做数据问答类应用核心是把 MCP 的调用结果和你的业务提示词拼在一起做自动化报表可以让模型定时触发 read_query 并把 CSV 落到你的存储做 Agent 工作流则可以把 StarRocks MCP Server 当成一个“数据工具节点”和其他工具编排在一起。如果你在接入过程中需要统一管理模型调用和密钥可以走 TaoToken 的 API Keys 页面创建密钥再对照接入文档把模型请求接到你的 MCP 客户端里想先验证模型对 SQL 的理解能力可以直接在模型对话里贴表结构和问题试跑如果是长期做编码类 Agent、需要稳定的模型调用额度Coding Plan 会更合适。StarRocks 负责把数据算快MCP 负责把数据递给模型剩下的就是你把场景想清楚。