Skip to main content
Glama
tracymacding

StarRocks MCP Server

by tracymacding
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
JavaScript
Hybrid

StarRocks MCP Server

MCP Node License

StarRocks MCP Server 是一个实现了 Model Context Protocol (MCP) 的服务器，为 AI 客户端提供 StarRocks 数据库的智能诊断和分析能力。

🎯 功能特性

  • ✅ MCP 协议支持: 完整实现 MCP Stdio Server 协议

  • ✅ 数据库连接: 连接 StarRocks 数据库执行 SQL 查询

  • ✅ 多客户端支持: 兼容 Gemini CLI、Claude Code CLI 等 MCP 客户端

  • ✅ 日志系统: 完整的请求/响应日志记录

  • ✅ 安全性: 支持环境变量配置，保护敏感信息

📦 架构

┌─────────────────────┐
│  MCP Client         │  (Claude Desktop, Cline, etc.)
│  (AI Application)   │
└──────────┬──────────┘
           │ MCP Protocol (Stdio)
           │
┌──────────▼──────────┐
│ StarRocks MCP Server│  (This Project)
│  - Tool Execution   │
│  - SQL Connection   │
│  - API Integration  │
└──────────┬──────────┘
           │
           ├─────────────────────┐
           │                     │
┌──────────▼──────────┐  ┌──────▼─────────────┐
│  StarRocks Database │  │ StarRocks Expert   │
│  (MySQL Protocol)   │  │ (Central API)      │
└─────────────────────┘  └────────────────────┘

🚀 快速开始

前置要求

  • Node.js >= 18.0.0

  • StarRocks 数据库实例

  • StarRocks Expert 中心服务（可选，用于高级分析）

  • DeepSeek API Key（可选，用于 LLM 分析）

安装

方法 1: 使用安装脚本（推荐）

# 克隆项目
git clone https://github.com/tracymacding/starrocks-mcp-server.git
cd starrocks-mcp-server

# 运行安装脚本
./install-starrocks-mcp.sh

安装脚本会自动：

  • 创建 ~/.starrocks-mcp/ 目录

  • 复制所有必要文件

  • 安装 npm 依赖

  • 生成配置文件模板

🔌 MCP 客户端配置

StarRocks MCP Server 支持任何实现了 MCP 协议的客户端。以下是主流客户端的详细配置指南。

方式 1: Claude Code CLI 配置（⭐ 强烈推荐）

Claude Code 是 Anthropic 官方的命令行 AI 编程工具，原生支持 MCP 协议。

为什么强烈推荐 Claude Code：

  • ✅ 最强的代码能力：Claude 在代码理解和生成方面表现卓越

  • ✅ 原生 MCP 支持：无需额外配置即可使用 MCP 工具

  • ✅ 支持 DeepSeek：可配置使用 DeepSeek 模型，大幅降低成本

  • ✅ 交互体验好：流式输出、多轮对话、上下文保持

  • ✅ 跨平台支持：macOS、Linux、Windows 全平台支持

1.1 安装 Claude Code CLI

快速安装：

Claude Code 提供了一键安装脚本，支持 macOS、Linux 和 Windows：

macOS/Linux：

# 一键安装
curl -fsSL https://claude.ai/install.sh | bash

Windows (PowerShell)：

# 一键安装
irm https://claude.ai/install.ps1 | iex

验证安装：

# 检查 Claude Code 是否已安装
claude --version

# 或直接启动
claude

1.2 配置 MCP Server

配置文件位置：~/.claude.json

编辑配置文件：

# macOS/Linux
nano ~/.claude.json

# Windows (PowerShell)
notepad "$env:USERPROFILE\.claude.json"

添加以下配置（根据实际情况修改）：

{
  "mcpServers": {
    "starrocks-expert": {
      "command": "node",
      "args": [
        "/path/to/starrocks-mcp-server/starrocks-mcp.js"
      ],
      "env": {
        "SR_HOST": "localhost",
        "SR_USER": "root",
        "SR_PASSWORD": "",
        "SR_PORT": "9030",
        "CENTRAL_API": "http://127.0.0.1:3002",
        "CENTRAL_API_TOKEN": "your_api_token_here",
        "PROMETHEUS_PROTOCOL": "http",
        "PROMETHEUS_HOST": "localhost",
        "PROMETHEUS_PORT": "9092"
      }
    }
  }
}

配置说明：

参数

说明

示例

command

执行命令（通常是 node）

node

args[0]

MCP Server 脚本的完整路径

/home/user/starrocks-mcp-server/starrocks-mcp.js

SR_HOST

StarRocks 数据库地址

localhost

SR_PORT

StarRocks 查询端口

9030

SR_USER

数据库用户名

root

SR_PASSWORD

数据库密码

留空或填写密码

CENTRAL_API

Expert 服务地址（可选）

http://127.0.0.1:3002

CENTRAL_API_TOKEN

API Token（可选）

向管理员索取

PROMETHEUS_PROTOCOL

Prometheus 协议

http 或 https

PROMETHEUS_HOST

Prometheus 地址

localhost

PROMETHEUS_PORT

Prometheus 端口

9092

查找 MCP Server 路径：

# 定位 starrocks-mcp.js 文件
find ~ -name "starrocks-mcp.js" 2>/dev/null

# 或者，如果你知道安装目录
cd /path/to/starrocks-mcp-server
pwd
# 输出完整路径，例如: /home/user/starrocks-mcp-server

1.3 使用 DeepSeek 模型（可选，推荐）

Claude Code 默认使用 Anthropic Claude 模型，但你也可以配置使用 DeepSeek 作为后端模型，成本更低且中文支持更好。

DeepSeek 优势：

  • ✅ 成本低廉（约 ¥1/百万 tokens 输入，比 Claude 便宜 90%+）

  • ✅ DeepSeek-V3 性能优秀

  • ✅ 中文理解和生成能力强

  • ✅ 官方支持 Anthropic API 兼容格式

参考文档：DeepSeek Anthropic API 兼容

配置方式

方式 A: 设置环境变量（推荐）

# 添加到 shell 配置文件（~/.bashrc 或 ~/.zshrc）
cat >> ~/.bashrc <<'EOF'

# DeepSeek 配置 for Claude Code
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=sk-your-deepseek-api-key-here  # 替换为你的 DeepSeek API Key
export ANTHROPIC_MODEL=deepseek-chat
export API_TIMEOUT_MS=600000  # 防止长输出超时
EOF

# 使配置生效
source ~/.bashrc

方式 B: 启动时设置

# 每次启动 Claude Code 时设置
ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic \
ANTHROPIC_AUTH_TOKEN=sk-your-deepseek-api-key \
ANTHROPIC_MODEL=deepseek-chat \
API_TIMEOUT_MS=600000 \
claude

获取 DeepSeek API Key：

  1. 访问 DeepSeek 开放平台

  2. 注册/登录账号

  3. 进入 API Keys 页面创建新的 API Key

  4. 复制 API Key（格式为 sk-xxxxxxxx）

DeepSeek 支持的功能

功能

支持情况

max_tokens

✅ 支持

stop_sequences

✅ 支持

stream

✅ 支持

system prompts

✅ 支持

temperature (0.0-2.0)

✅ 支持

top_p

✅ 支持

tool use (MCP 工具调用)

✅ 支持

thinking mode

✅ 支持

图片内容

❌ 不支持

文档类型

❌ 不支持

验证 DeepSeek 配置
# 启动 Claude Code
claude

# 如果配置正确，Claude Code 会使用 DeepSeek 模型
# 可以通过询问模型来验证
> 你是什么模型？

# DeepSeek 会回复类似：我是 DeepSeek...

注意：使用 DeepSeek 时，部分 Claude 特有功能（如图片分析）将不可用，但对于代码编写和 StarRocks 诊断等文本任务完全够用。

1.4 验证配置

  1. 启动 Claude Code CLI：

    # 方式 1: 直接启动
claude

# 方式 2: 在项目目录中启动
cd /path/to/your/project
claude

  2. 检查 MCP Server 连接：

    在 Claude Code 中输入：

    列出所有可用的 MCP 工具

    或者：

    /tools

  3. 测试 StarRocks 诊断功能：

    帮我分析 StarRocks 的存储健康状况

    或者：

    查询最近 1 小时的慢查询

  4. 预期结果：

    Claude Code 应该能够：

    • ✅ 自动连接到 StarRocks MCP Server

    • ✅ 列出所有可用工具（34 个 StarRocks 诊断工具）

    • ✅ 执行 SQL 查询并返回分析结果

    • ✅ 提供专业的诊断建议

1.5 故障排查

问题 1: 提示 "MCP Server not found" 或 "Connection failed"

解决方法：

# 检查配置文件是否存在
cat ~/.claude.json

# 检查配置文件 JSON 格式是否正确
cat ~/.claude.json | jq .

# 手动测试 MCP Server 是否能启动
export SR_HOST=localhost
export SR_PORT=9030
export SR_USER=root
export SR_PASSWORD=
export CENTRAL_API=http://127.0.0.1:3002
export CENTRAL_API_TOKEN=your_token
export PROMETHEUS_PROTOCOL=http
export PROMETHEUS_HOST=localhost
export PROMETHEUS_PORT=9092

node /path/to/starrocks-mcp-server/starrocks-mcp.js
# 应该启动并等待输入

问题 2: 工具执行失败

解决方法：

  • 检查 StarRocks 数据库连接：

    mysql -h 127.0.0.1 -P 9030 -u root -e "SELECT 1"

  • 检查中心 API 服务器（如果使用）：

    curl http://localhost:80/health

问题 3: 配置文件路径不正确

检查配置文件：

# 检查配置文件是否存在
ls -la ~/.claude.json

# 查看配置文件内容
cat ~/.claude.json

方式 2: OpenCode 配置

OpenCode 是一款开源的 AI 编程 Agent，支持终端、桌面应用和 IDE 插件，原生支持 MCP 协议。

2.1 安装 OpenCode

一键安装（推荐）：

curl -fsSL https://opencode.ai/install | bash

通过 npm 安装：

npm install -g opencode-ai

通过 Homebrew 安装（macOS/Linux）：

brew install anomalyco/tap/opencode

验证安装：

opencode --version

2.2 配置 MCP Server

OpenCode 使用 opencode.jsonc 作为配置文件，可放在项目目录或用户主目录下。

编辑或创建配置文件：

# 全局配置（推荐）
nano ~/.config/opencode/opencode.jsonc

# 或在项目目录中创建（仅对该项目生效）
nano opencode.jsonc

添加以下配置（根据实际情况修改）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "starrocks-expert": {
      "type": "local",
      "command": [
        "node",
        "/path/to/starrocks-mcp-server/starrocks-mcp.js"
      ],
      "enabled": true,
      "environment": {
        "SR_HOST": "localhost",
        "SR_USER": "root",
        "SR_PASSWORD": "",
        "SR_PORT": "9030",
        "CENTRAL_API": "http://127.0.0.1:3002",
        "CENTRAL_API_TOKEN": "your_api_token_here",
        "PROMETHEUS_PROTOCOL": "http",
        "PROMETHEUS_HOST": "localhost",
        "PROMETHEUS_PORT": "9092"
      }
    }
  }
}

配置说明：

参数

说明

示例

type

固定填 "local"

local

command[0]

执行命令

node

command[1]

MCP Server 脚本完整路径

/home/user/starrocks-mcp-server/starrocks-mcp.js

SR_HOST

StarRocks 数据库地址

localhost

SR_PORT

StarRocks 查询端口

9030

SR_USER

数据库用户名

root

SR_PASSWORD

数据库密码

留空或填写密码

CENTRAL_API

Expert 服务地址（可选）

http://127.0.0.1:3002

CENTRAL_API_TOKEN

API Token（可选）

向管理员索取

PROMETHEUS_PROTOCOL

Prometheus 协议

http 或 https

PROMETHEUS_HOST

Prometheus 地址

localhost

PROMETHEUS_PORT

Prometheus 端口

9092

2.3 启动 OpenCode 并验证

# 进入项目目录
cd /path/to/your/project

# 启动 OpenCode
opencode

在 OpenCode 中验证 MCP 连接：

# 查看所有已连接的 MCP 服务器
opencode mcp list

# 预期输出中应包含：
# ✓ starrocks-expert: node .../starrocks-mcp.js (local) - Connected
#   Tools: 34

2.4 使用 StarRocks 诊断功能

在 OpenCode 对话中直接输入：

帮我分析 StarRocks 的存储健康状况

或：

查询最近 1 小时的慢查询

OpenCode 会自动调用 StarRocks MCP 工具完成分析。

2.5 故障排查

问题 1: MCP Server 无法连接

# 检查配置文件格式
cat ~/.config/opencode/opencode.jsonc

# 手动测试 MCP Server 能否启动
node /path/to/starrocks-mcp-server/starrocks-mcp.js
# 应该启动并等待输入

问题 2: 找不到 MCP 工具

# 检查 enabled 字段是否为 true
# 检查 command 路径是否正确
ls -la /path/to/starrocks-mcp-server/starrocks-mcp.js

方式 3: Gemini CLI 配置

Gemini CLI 是 Google 官方的命令行工具，原生支持 MCP 协议。根据是否需要使用 DeepSeek 作为 LLM 提供商，有两种配置方式：

方式 3A: 原生 Gemini CLI（仅支持 Google Gemini）

如果你只需要使用 Google Gemini API，可以安装原生版本。

3A.1 安装原生 Gemini CLI

官方文档: Gemini CLI Installation

# 全局安装 Gemini CLI
npm install -g @google/gemini-cli

# 验证安装
gemini --version

参考资源:

3A.2 配置 Google Gemini API Key
# 设置 API Key（从 https://aistudio.google.com/apikey 获取）
export GOOGLE_API_KEY="your-google-api-key-here"

# 或添加到 shell 配置文件
echo 'export GOOGLE_API_KEY="your-google-api-key-here"' >> ~/.bashrc
source ~/.bashrc
3A.3 配置 MCP Server

创建或编辑 ~/.gemini/settings.json 文件：

mkdir -p ~/.gemini
nano ~/.gemini/settings.json

添加以下配置（根据实际情况修改路径和连接信息）：

{
  "mcpServers": {
    "starrocks-expert": {
      "command": "node",
      "args": [
        "/path/to/starrocks-mcp-server/starrocks-mcp.js"
      ],
      "env": {
        "SR_HOST": "localhost",
        "SR_USER": "root",
        "SR_PASSWORD": "",
        "SR_PORT": "9030",
        "CENTRAL_API": "http://127.0.0.1:3002",
        "CENTRAL_API_TOKEN": "your_api_token_here",
        "PROMETHEUS_PROTOCOL": "http",
        "PROMETHEUS_HOST": "localhost",
        "PROMETHEUS_PORT": "9092"
      }
    }
  }
}
3A.4 验证配置
# 启动 Gemini CLI
gemini

# 检查 MCP 连接状态
> /mcp list

# 预期输出：
# ✓ starrocks-expert: node .../starrocks-mcp.js (stdio) - Connected
#   Tools: 34

# 测试工具
> 帮我查看 StarRocks 的存储健康状况

注意：原生 Gemini CLI 仅支持 Google Gemini API，不支持 DeepSeek 等其他 LLM 提供商。如需使用 DeepSeek，请使用方式 2B。

方式 3B: 定制版 Gemini CLI（支持 DeepSeek，推荐）

定制版 Gemini CLI 扩展了原生版本，支持 DeepSeek 等多种 LLM 提供商，成本更低且性能优秀。

3B.1 安装定制版 Gemini CLI
# 克隆定制版 Gemini CLI 项目
git clone https://github.com/tracymacding/gemini-cli.git
cd gemini-cli

# 安装依赖
npm install

# 构建项目
npm run build

# 全局链接（方便直接使用 gemini 命令）
npm link
3B.2 验证安装
gemini --version
# 应该显示版本号，例如: 0.8.0
3B.3 配置 DeepSeek API Key

DeepSeek 优势：

  • ✅ 比 Google Gemini 便宜约 90%（¥1/百万 tokens 输入）

  • ✅ 性能优秀（DeepSeek-V3）

  • ✅ 中文支持更好

方式 A: 使用 .env 文件（推荐）

cd gemini-cli

# 创建 .env 文件
cat > .env <<'EOF'
# DeepSeek API Key
# 获取地址: https://platform.deepseek.com/
DEEPSEEK_API_KEY=sk-your-deepseek-api-key-here
EOF

方式 B: 设置环境变量

# 临时设置（当前终端有效）
export DEEPSEEK_API_KEY="sk-your-deepseek-api-key-here"

# 永久设置（添加到 shell 配置）
echo 'export DEEPSEEK_API_KEY="sk-your-deepseek-api-key-here"' >> ~/.bashrc
source ~/.bashrc
3B.4 配置 MCP Server

创建或编辑 ~/.gemini/settings.json 文件：

mkdir -p ~/.gemini
nano ~/.gemini/settings.json

添加以下配置（根据实际情况修改路径和连接信息）：

{
  "mcpServers": {
    "starrocks-expert": {
      "command": "node",
      "args": [
        "/path/to/starrocks-mcp-server/starrocks-mcp.js"
      ],
      "env": {
        "SR_HOST": "localhost",
        "SR_USER": "root",
        "SR_PASSWORD": "",
        "SR_PORT": "9030",
        "CENTRAL_API": "http://127.0.0.1:3002",
        "CENTRAL_API_TOKEN": "your_api_token_here",
        "PROMETHEUS_PROTOCOL": "http",
        "PROMETHEUS_HOST": "localhost",
        "PROMETHEUS_PORT": "9092"
      }
    }
  }
}

配置说明：

参数

说明

示例

args[0]

MCP Server 脚本的完整路径

/home/user/starrocks-mcp-server/starrocks-mcp.js

SR_HOST

StarRocks 数据库地址

localhost 或 192.168.1.100

SR_PORT

StarRocks 查询端口

9030 (默认)

SR_USER

数据库用户名

root

SR_PASSWORD

数据库密码

留空或填写实际密码

CENTRAL_API

Expert 服务地址（可选）

http://127.0.0.1:3002

CENTRAL_API_TOKEN

API 认证 Token（可选）

向管理员索取

PROMETHEUS_PROTOCOL

Prometheus 协议

http 或 https

PROMETHEUS_HOST

Prometheus 地址

localhost

PROMETHEUS_PORT

Prometheus 端口

9092

3B.5 验证配置

使用启动脚本（推荐）：

cd gemini-cli
./start-gemini-cli.sh

或手动启动：

# 启动 Gemini CLI 并使用 DeepSeek
gemini --provider deepseek -m deepseek-chat

# 检查 MCP 连接状态
> /mcp list

# 预期输出：
# ✓ starrocks-expert: node .../starrocks-mcp.js (stdio) - Connected
#   Tools: 34

# 查看可用工具
> /tools

# 测试工具
> 帮我分析 StarRocks 的存储健康状况

预期输出示例：

🤖 启动 Gemini CLI (DeepSeek + MCP)
====================================

✅ 已加载 .env 配置
✅ DeepSeek API Key: sk-76b76...
📡 检查中心 API 服务器...
   ✅ API 服务器运行正常
🔧 检查 MCP 配置...
   ✅ MCP 服务器已连接

🚀 启动 Gemini CLI...

💡 使用的功能:
   • DeepSeek 模型 (deepseek-chat)
   • MCP 工具 (StarRocks 诊断)

🔄 多集群运维

StarRocks MCP Server 支持在单个进程中管理多个集群，通过 use_cluster / list_clusters 工具实现运行时切换。

配置集群

在 MCP Server 同级目录创建 clusters.json 文件（可参考 clusters.example.json）：

{
  "prod": {
    "name": "生产集群",
    "sr_host": "192.168.51.111",
    "sr_port": 9030,
    "sr_user": "root",
    "sr_password": "your_password",
    "prometheus_protocol": "http",
    "prometheus_host": "192.168.51.100",
    "prometheus_port": 30090,
    "ssh_user": "admin",
    "ssh_jump_host": "192.168.51.101",
    "central_api": "http://127.0.0.1:80",
    "central_api_token": "your_token"
  },
  "staging": {
    "name": "测试集群",
    "sr_host": "10.0.1.50",
    "sr_port": 9030,
    "sr_user": "root",
    "sr_password": "",
    "prometheus_host": "10.0.1.60",
    "prometheus_port": 9090,
    "central_api": "http://127.0.0.1:80",
    "central_api_token": "your_token"
  }
}

也可通过环境变量 CLUSTERS_CONFIG 指定配置文件路径。

注意：clusters.json 包含数据库密码等敏感信息，已默认加入 .gitignore，请勿提交到仓库。

配置项说明

字段

必填

说明

默认值

name

否

集群显示名称

使用 key 作为名称

sr_host

是

StarRocks FE 地址

localhost

sr_port

否

StarRocks 查询端口

9030

sr_user

否

数据库用户名

root

sr_password

否

数据库密码

空

prometheus_protocol

否

Prometheus 协议

http

prometheus_host

否

Prometheus 地址

localhost

prometheus_port

否

Prometheus 端口

9090

ssh_user

否

SSH 用户名

当前系统用户

ssh_jump_host

否

SSH 跳板机地址

空（直连）

ssh_key_path

否

SSH 私钥路径

空（使用 agent）

central_api

否

中心 API 地址

继承环境变量

central_api_token

否

中心 API Token

继承环境变量

architecture

否

手动指定架构类型（shared_data / shared_nothing），跳过自动检测

自动检测

使用方式

查看集群列表：

帮我看看当前有哪些集群

MCP Server 会调用 list_clusters 工具，返回所有已配置集群的信息，包括架构类型和当前激活状态。

切换集群：

帮我切换到测试集群

MCP Server 会调用 use_cluster("staging")，切换后：

  • 自动重置所有连接（数据库、SSH、Prometheus）

  • 自动检测集群架构（shared_data / shared_nothing）

  • 后续所有工具调用将使用新集群的配置

架构检测：

切换集群时，MCP Server 会自动检测集群架构类型。当前所有诊断工具仅支持 shared-data（存算分离） 架构：

  • shared_data：正常使用所有工具

  • shared_nothing：工具调用会被拦截，提示切换到 shared-data 集群

  • 检测失败（如网络不通）：默认放行，不阻断使用

兼容性

场景

行为

无 clusters.json

完全退化为单集群模式，从环境变量读取配置，不注册集群管理工具

clusters.json 为空 {}

同上

配置 1 个集群

启动时自动激活该集群

配置 N 个集群

启动时自动激活第一个集群，支持 use_cluster 切换

配置验证清单

完成配置后，使用以下清单验证：

  • MCP Server 能成功启动（没有报错）

  • 客户端显示 "Connected" 状态

  • 可以看到工具列表（通常 30+ 个工具）

  • 能成功执行一个测试工具（例如查询数据库版本）

  • 日志文件正常生成（./logs/ 目录）

故障排查

如果连接失败，请按顺序检查：

  1. 检查 Node.js 版本：

    node --version  # 必须 >= 18.0.0

  2. 检查文件路径：

    ls -la /path/to/starrocks-mcp.js  # 文件必须存在

  3. 检查数据库连接：

    mysql -h $SR_HOST -P $SR_PORT -u $SR_USER -p

  4. 查看日志：

    tail -f /path/to/starrocks-mcp-server/logs/starrocks-mcp-*.log

  5. 手动测试 MCP Server：

    cd /path/to/starrocks-mcp-server
node starrocks-mcp.js
# 应该启动并等待 MCP 协议输入

🐛 故障排查

MCP Server 无法连接

  1. 检查 Node.js 版本：node --version（需要 >= 18）

  2. 检查环境变量：cat .env

  3. 查看日志：tail -f logs/starrocks-mcp-*.log

数据库连接失败

  1. 测试数据库连接：

mysql -h $SR_HOST -P $SR_PORT -u $SR_USER -p

  1. 检查防火墙规则

  2. 确认数据库用户权限

工具执行失败

  1. 检查日志中的错误信息

  2. 确认 StarRocks Expert 服务是否运行

  3. 验证 API Token 是否正确

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tracymacding/starrocks-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server