手把手教你做 StarRocks Agent：用 MCP 打通 DeepChat 与 Python 查询链路

1. 为什么要在本地搭一个 StarRocks Agent

StarRocks 作为一款 MPP 架构的实时分析数据库，日常用起来最烦的其实不是写 SQL，而是那些重复的巡检、建表、造数据、看 profile 的活儿。业务方一句“帮我看看集群现在啥情况”，你就得切终端、连客户端、敲一堆SHOW命令；想验证一个索引效果，又得手动写测试数据、跑查询、再翻 profile。这些操作本身不难，但碎、重复、容易漏。

所谓 StarRocks Agent，本质就是让大模型通过 MCP（Model 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 uv

uv是后面跑 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_source=taotoken_aicg_blog_end，注册后在控制台创建 API Key 即可。

具体操作：登录后进控制台，在 API Keys 页面新建一个 Key，复制出来。然后在 DeepChat 的模型设置里，把 Base URL 填成https://taotoken.net/api，API 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 能连上你的 StarRocks：

STARROCKS_URL=root:password@localhost: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:password@localhost:9030/my_database" } } } }

这段配置里，command是uv，args用--directory指定 MCP Server 源码目录，再run mcp-server-starrocks启动。env里的STARROCKS_URL格式是user:password@host:port/database，database 可以省略，省略后默认连到实例但不选库。保存后 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( command="uv", args=[ "--directory", "/Users/yourname/code/mcp-server-starrocks", "run", "mcp-server-starrocks", ], env={"STARROCKS_URL": "root:password@localhost: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 ID，Key 不用动，多个客户端也能共用一份配额。

5. 常见报错与排查对照

跑这条链路最容易踩的坑集中在连接和配置上，下面按真实报错对照排查。

401 Unauthorized：出现在 DeepChat 调模型时，说明 TaoToken 的 API Key 不对或没填。检查 Base URL 是否为https://taotoken.net/api，Key 是否复制完整（前后不要有空格），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/api，Model 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:password@host: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/api，Key 用控制台创建的；Python 脚本里如果也要调模型（比如做自动化分析），同样把请求地址指过去；Claude Code 这类编码工具，在 Coding Plan 里开通后按文档配置。三件套——Base URL、Key、Model ID——在每个客户端都填全，不要漏。

需要新建 Key 或查看用量，去控制台的 API Keys 页面；接入细节和可用模型列表，看接入文档；想先在网页里验证模型是否可用，用模型对话页面直接试；长期做编码和 Agent 开发，Coding Plan 更划算。这些入口在 TaoToken 官网都能找到，按你的场景选就行。

最后留一个实用技巧：MCP Server 的STARROCKS_URL里如果带密码，不要把配置文件提交到 Git。可以用环境变量注入，或者在本地用一个不纳入版本管理的.env文件，DeepChat 配置里引用环境变量。这样既安全，换环境时也只需要改一处。