1. 为什么要在本地搭一个 StarRocks AgentStarRocks 作为一款 MPP 架构的实时分析数据库日常用起来最烦的其实不是写 SQL而是那些重复的巡检、建表、造数据、看 profile 的活儿。业务方一句“帮我看看集群现在啥情况”你就得切终端、连客户端、敲一堆SHOW命令想验证一个索引效果又得手动写测试数据、跑查询、再翻 profile。这些操作本身不难但碎、重复、容易漏。所谓 StarRocks Agent本质就是让大模型通过 MCPModel Context Protocol拿到 StarRocks 的查询能力你用自然语言描述意图模型自己决定调哪个工具、拼什么 SQL、怎么解读结果。MCP 在这里扮演的是“工具总线”的角色它把 StarRocks 的查询、建表、profile 分析等能力封装成模型可调用的函数DeepChat 作为客户端负责对话和工具编排Python 则负责把整条链路串起来、做二次开发和自动化。这套组合适合谁一是本地做数据分析的同学手头有 StarRocks 测试集群想用自然语言快速查数二是数据平台开发想基于 MCP 做二次开发把巡检、SQL 审核、性能诊断做成 Agent 能力三是刚接触 MCP 协议、想找一个真实数据库场景练手的工程师。整条链路跑通之后你可以在 DeepChat 里直接说“看下集群现状”模型会自己调SHOW FRONTENDS、SHOW BACKENDS之类的命令并汇总结果比手动敲命令省事得多。下面我会从环境准备开始一步步给出可复制的 MCP 配置、Python 调用示例以及一次完整的自然语言问答验证。模型请求地址部分我会把 DeepChat 的模型通道统一改到 TaoToken 管理这样 Key 和调用通道集中在一处换模型、查用量都方便。2. 前置环境与 TaoToken 通道准备先说环境。Python 建议 3.12用 pyenv 管理版本比较干净pyenv install 3.12 pyenv global 3.12.11 pip3 install uvuv是后面跑 MCP Server 的关键它可以直接从源码目录启动 Python 包不用你先pip install。StarRocks 这边你需要一个可连的实例本地 Docker 起一个也行记住 FE 的 9030 端口和账号密码。DeepChat 去官网下载对应平台的安装包即可它支持 MCP 配置是我们这次用的 Agent 客户端。接下来是模型通道。DeepChat 默认会让你填模型服务商的 Base URL 和 API Key如果你手头有多个模型、多个 Key散落在各个客户端里很难管理。我的做法是统一走 TaoToken把模型请求地址指过去Key 也只维护一份。TaoToken 的 API 地址是https://taotoken.net/api官网在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end注册后在控制台创建 API Key 即可。具体操作登录后进控制台在 API Keys 页面新建一个 Key复制出来。然后在 DeepChat 的模型设置里把 Base URL 填成https://taotoken.net/apiAPI Key 填你刚创建的Model ID 填你要用的模型名比如claude-sonnet-4-20250514这类以你账号下可用的为准。这三件套——Base URL、Key、Model ID——是后面所有配置的基础缺一不可。注意Base URL 末尾不要多加/v1之类的路径TaoToken 的接入文档里写得很清楚按文档填就行。填错最常见的表现就是 404 或 401。如果你还想在命令行里用 Claude Code 做编码辅助也可以在 TaoToken 的 Coding Plan 里开通对应套餐把 Claude Code 的请求也指到同一个通道这样对话、编码、Agent 三条链路的 Key 就统一了。不过这篇的重点是 StarRocks Agent模型通道准备好就可以往下走。3. 可复制的 MCP 服务配置与 Python 调用StarRocks 官方提供了 MCP Server仓库在https://github.com/StarRocks/mcp-server-starrocks.git。先克隆到本地git clone https://github.com/StarRocks/mcp-server-starrocks.git cd mcp-server-starrocks克隆完先做一次连通性自测确认 MCP Server 能连上你的 StarRocksSTARROCKS_URLroot:passwordlocalhost:9030/my_database \ uv run mcp-server-starrocks --test如果输出里出现Starting StarRocks MCP Server、Tool test completed以及类似Database db1 information_schema Total rows: 2的内容说明 MCP 到 StarRocks 的链路是通的。这一步很关键很多人后面 DeepChat 里报错根子其实在这里就连不上。接下来配置 DeepChat。在 DeepChat 的设置页面找到 MCP 配置入口新增一个 MCP Server把下面这段 JSON 填进去注意把path/to/mcp-server-starrocks换成你实际的克隆路径STARROCKS_URL换成你的实例信息{ mcpServers: { mcp-server-starrocks: { command: uv, args: [ --directory, /Users/yourname/code/mcp-server-starrocks, run, mcp-server-starrocks ], env: { STARROCKS_URL: root:passwordlocalhost:9030/my_database } } } }这段配置里command是uvargs用--directory指定 MCP Server 源码目录再run mcp-server-starrocks启动。env里的STARROCKS_URL格式是user:passwordhost:port/databasedatabase 可以省略省略后默认连到实例但不选库。保存后 DeepChat 会尝试拉起这个 MCP Server你可以在 MCP 状态里看到它是否 connected。Python 侧如果你想自己写调用逻辑可以用mcp官方 SDK 起一个 stdio 客户端连到同一个 MCP Server然后列出工具、调用工具。下面是一个最小示例import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): params StdioServerParameters( commanduv, args[ --directory, /Users/yourname/code/mcp-server-starrocks, run, mcp-server-starrocks, ], env{STARROCKS_URL: root:passwordlocalhost:9030/my_database}, ) async with stdio_client(params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools await session.list_tools() print(可用工具:, [t.name for t in tools.tools]) result await session.call_tool( run_query, {query: SHOW FRONTENDS} ) print(result.content) asyncio.run(main())这段代码先initialize握手再list_tools看 MCP Server 暴露了哪些工具不同版本工具名可能略有差异以实际输出为准然后调run_query执行一条SHOW FRONTENDS。跑通这个你就有了一个不依赖 DeepChat 的纯 Python 查询链路后面做自动化巡检、定时任务都可以基于它扩展。4. 一次完整的自然语言问答验证配置好之后来一次端到端验证。打开 DeepChat确认 MCP Server 状态是 connected模型通道指向 TaoToken。然后在对话框里输入看下集群现状模型会自己决定调用 MCP 工具。正常情况下它会先调run_query执行SHOW FRONTENDS和SHOW BACKENDS把 FE、BE 的节点状态、版本、存活情况汇总成一段可读的文字返回给你。你不需要告诉它具体敲哪条命令它根据工具描述自己选。接着试建表和造数据给我在 db1 库建一个雇员表字段有 id、name、department、salary模型会拼出CREATE TABLE语句并调用工具执行。这里要注意建表属于写操作部分 MCP Server 版本默认只开放只读查询如果报权限或工具不存在需要检查 MCP Server 的配置是否允许 DDL。建完表继续写100条测试数据进去模型会生成INSERT语句可能分批插入。数据进去后用一条分析语句验证给我分析一下这个语句的 profile select department, count(1) from employees group by department;模型会先执行查询再尝试获取 profile 信息比如通过SHOW PROFILELIST或对应工具把执行计划、耗时、扫描行数等关键指标解读出来。到这一步整条链路——DeepChat 对话 → MCP 工具调用 → StarRocks 执行 → 结果回传 → 模型解读——就完整跑通了。实测下来这套流程对本地数据分析场景很顺手尤其是巡检和临时查数省掉了大量切终端、拼命令的时间。模型通道走 TaoToken 之后换模型只需要改 Model IDKey 不用动多个客户端也能共用一份配额。5. 常见报错与排查对照跑这条链路最容易踩的坑集中在连接和配置上下面按真实报错对照排查。401 Unauthorized出现在 DeepChat 调模型时说明 TaoToken 的 API Key 不对或没填。检查 Base URL 是否为https://taotoken.net/apiKey 是否复制完整前后不要有空格Model ID 是否在你账号可用范围内。如果 Key 没问题还报 401去控制台确认 Key 是否被禁用或额度耗尽。local proxy failed / connection refused出现在 MCP Server 启动阶段通常是uv路径不对或--directory指向的目录不存在。先在终端手动跑一遍uv run mcp-server-starrocks --test确认能起来再检查 DeepChat 配置里的路径是不是绝对路径、有没有拼错。Windows 下路径要用双反斜杠或正斜杠。Error reading choices / 返回体解析失败模型通道返回了非预期结构常见于 Base URL 填成了带/v1的地址或者 Model ID 填了一个不存在的模型。把 Base URL 改回https://taotoken.net/apiModel ID 换成文档里列出的可用模型再试。OAuth / 鉴权相关报错如果你用的是 Claude Code 或 Codex 这类需要 OAuth 的客户端报 OAuth 错误通常是本地凭证过期或没登录。这类客户端建议走 TaoToken 的 Coding Plan按接入文档配置auth.json或对应凭证文件把 Base URL、Key、Model ID 三件套填全不要只填一半。MCP 工具列表为空DeepChat 显示 connected 但list_tools返回空多半是 MCP Server 版本和客户端协议版本不匹配。升级mcp-server-starrocks到最新或检查 DeepChat 的 MCP 协议版本设置。Python 侧可以用第 3 节的脚本单独list_tools验证排除是客户端问题还是服务端问题。STARROCKS_URL 连不上报连接超时或认证失败检查格式user:passwordhost:port/database密码里如果有特殊字符要 URL 编码。本地 Docker 起的 StarRocks确认 9030 端口映射出来了docker ps看一眼。排查顺序建议从下往上先确认 StarRocks 本身能连再确认 MCP Server 能起再确认 DeepChat 能拉起 MCP最后确认模型通道正常。这样定位最快。6. 把 Key 和调用通道统一到 TaoToken链路跑通之后建议把模型请求地址固定到 TaoToken理由很实际DeepChat、Python 脚本、Claude Code 这些客户端如果各自维护一份 Key换模型、查用量、控额度都很麻烦。统一到https://taotoken.net/api之后你只需要在控制台管理一份 Key所有客户端共用。具体做法DeepChat 里 Base URL 填https://taotoken.net/apiKey 用控制台创建的Python 脚本里如果也要调模型比如做自动化分析同样把请求地址指过去Claude Code 这类编码工具在 Coding Plan 里开通后按文档配置。三件套——Base URL、Key、Model ID——在每个客户端都填全不要漏。需要新建 Key 或查看用量去控制台的 API Keys 页面接入细节和可用模型列表看接入文档想先在网页里验证模型是否可用用模型对话页面直接试长期做编码和 Agent 开发Coding Plan 更划算。这些入口在 TaoToken 官网都能找到按你的场景选就行。最后留一个实用技巧MCP Server 的STARROCKS_URL里如果带密码不要把配置文件提交到 Git。可以用环境变量注入或者在本地用一个不纳入版本管理的.env文件DeepChat 配置里引用环境变量。这样既安全换环境时也只需要改一处。